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Preface 


Intended Audience 

This manual is intended for programmers who want to invoke and 
manipulate VAX/VMS utilities from a program. 


Structure of This Document 

This document contains 12 sections. Section 1 introduces utility routines and 
describes the documentation format that is used to describe each set of utility 
routines, as well as individual routines in each set. 

Sections 2 through 12 each describe one set of utility routines. Each section 
contains an introduction to that set of utility routines, a programming example 
to illustrate the use of the routines in the set, and a detailed decription of each 
routine. 


Associated Documents 

The VAX Procedure Calling and Condition Handling Standard, which is 
documented in the Introduction to VAX/VMS System Routines, contains useful 
information for all programmers. The Introduction to VAX/VMS System 
Routines also describes in detail the documentation format of the routine 
descriptions. 

Some sets of utility routines documented in this manual invoke and 
manipulate utilities that have a command level interface. Consult the 
following manuals for a description of the command level interface. 

• VAX/VMS Access Control List Editor Reference Manual 

• VAX/VMS Command Definition Utility Reference Manual 

• VAX/VMS Convert and Convert/Reclaim Utility Reference Manual 

• VAX EDT Reference Manual 

• VAX/VMS File Definition Language Facility Reference Manual 

• VAX/VMS Librarian Reference Manual 

• VAX/VMS Sort/Merge Utility Reference Manual 

• VAX Text Processing Utility Reference Manual 









Preface 


Conventions Used in This Document 

The documentation template for utility routines, which is described in the 
Introduction to VAX/VMS System Routines , describes the conventions used in 
this manual, as well as the organizational approach used to document each 
utility routine. 

The following table describes additional conventions that may appear in this 
manual. 


Convention 

Meaning 

[ret] 

A symbol with a one- to six-character 
abbreviation indicates that you press a key 
on the terminal, for example, 1 RET| . 

|CTRL/x| 

The phrase CTRL/x indicates that you 
must press the key labeled CTRL while you 
simultaneously press another key, for example, 
CTRL/C, CTRL/Y, CTRL/O. 

$ SHOW TIME 

05-JUN-1985 1 1:55:22 

Command examples show all output lines or 
prompting characters that the system prints 
or displays in black letters. All user-entered 
commands are shown in red letters. 

$ TYPE MYFILE.DAT 

Vertical series of periods, or ellipsis, mean 
either that not all the data that the system 
would display in response to the particular 
command is shown or that not all the data a 
user would enter is shown. 

file-spec,... 

Horizontal ellipsis indicates that additional 
parameters, values, or information can be 
entered. 

[logical-name] 

Square brackets indicate that the enclosed item 
is optional. (Square brackets are not, however, 
optional in the syntax of a directory name in a 
file specification or in the syntax of a substring 
specification in an assignment statement.) 

quotation marks 
apostrophes 

The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe (') is used to refer to a single 
quotation mark. 









New and Changed Features 


New Sets of Utility Routines 

The following sets of utility routines are new with VAX/VMS Version 4.4: 

• Access Control List (ACL) Editor Routine 

• VAX Text Processing Utility (VAXTPU) Routines 


Argument Characteristics 


The descriptions of each argument in the utility routines contains information 
about the argument's characteristics—VMS Usage, type, access, and 
mechanism. 





xiii 
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Introduction to Utility Routines 



1.1 Overview 

A set of utility routines is a set of routines that perform a particular task or set 
of tasks. For example, the Print Symbiont Modification (PSM) routines can be 
used to modify the VAX/VMS print symbiont, and the EDT routines can be 
used to invoke the EDT editor from a program. 

Some of the tasks performed by utility routines documented in this manual 
can also be performed by users at the DCL level. For example, the DCL 
command EDIT invokes the EDT editor. 

Some DCL commands invoke VAX/VMS utilities that allow users to perform 
tasks at their terminals, and some of these tasks can also be performed at the 
programming level through the use of the utility routines documented in this 
manual. 

When using a set of utility routines that performs the same tasks as a 
VAX/VMS utility, you should read the documentation for that utility; doing 
so will provide you with additional information on the tasks that the routines 
can, as a set, perform. The following list shows which VAX/VMS utilities 
have corresponding utility routines: 


Utility or Editor 

Utility Routines 

Access Control List Editor 

ACL Editor routine 

Command Definition Utility 

CLI routines 

Convert and Convert/Reclaim Utilities 

CONV routines 

EDT Editor 

EDT routines 

File Definition Language Facility 

FDL routines 

Library Utility 

LBR routines 

Sort/Merge Utility 

SOR routines 

VAX Text Processing Utility 

VAXTPU routines 

When a set of utility routines performs functions that cannot be performed by 
invoking a VAX/VMS utility, the functions provided by that set of routines is 
termed a facility. The following facilities have no other user interface except 
the programming interface provided by the utility routines described in this 
manual. 

Facility 

Utility Routines 

Data Compression/Expansion Facility 

DCX routines 

Print Symbiont Modification Facility 

PSM routines 

Symbiont/Job-Controller Interface Facility 

SMB routines 


The utility routines described in this manual are called in the same way as 
all other system routines in the VAX/VMS operating system environment. 


INTRO-1 











Introduction to Utility Routines 

Overview 


which is to say that utility routines conform to the VAX Procedure Calling 
and Condition Handling Standard. 

Each set of utility routines is documented in one section of this book. 

Each section has the following three major components, each of which is 
documented as a major heading. 

• An introduction to the set of utility routines. This subsection discusses the 
utility routines as a group and explains how to use them. 

• A programming example that illustrates how the utility routines are used. 

• A series of descriptions of each utility routine in the set. Each utility 
routine is documented according to the format described in the following 
section. 


INTRO-2 
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Access Control List (ACL) Editor Routine 


2.1 






Introduction to the ACL Editor Routine 

This section describes the Access Control List (ACL) routine, ACLEDIT$EDIT. 
User-written applications can use this callable interface of the ACL Editor to 
manipulate Access Control Lists. 

The ACL Editor is a VAX/VMS utility that allows users to create and maintain 
access control lists. Using ACLs, you can finely tune the type of access to 
files, devices, global sections, logical name tables, or mailboxes available to 
system users. 

Currently, the ACL Editor provides one callable interface that allows 
application program to define an object for editing. 


ACL—1 







Access Control List (ACL) Editor Routine 

Example of Using the ACL Editor Routine 


2.2 Example of Using the ACL Editor Routine 

Example ACL-1 Calling the ACL Editor With a VAX BLISS 
Program 


MODULE MAIN (LANGUAGE (BLISS32), MAIN = STARTUP) = 
BEGIN 

LIBRARY 'SYS$LIBRARY:LIB'; 

ROUTINE STARTUP = 


BEGIN 


LOCAL 

STATUS, ! Routine return status 

ITMLST : BLOCKVECTOR [6, ITM$S_ITEM, BYTE]; 

! ACL editor item list 

EXTERNAL LITERAL 
ACLEDIT$V_JOURNAL, 

ACLEDIT$V_PROMPT_MODE, 

ACLEDIT$C_OBJNAM, 

ACLEDIT$C_OBJTYP, 

ACLEDIT$C_OPTIONS; 


EXTERNAL ROUTINE 

ACLEDIT$EDIT : ADDRESSING.MODE (GENERAL), ! Main routine 


CLI$GET_VALUE, ! Get qualifier value 
CLI$PRESENT, ! See if qualifier present 
LIB$PUT_OUTPUT, ! General output routine 
STR$COPY_DX; ! Copy string by descriptor 


Set up the item list to pass back to TPU so it can figure out what to do. 


CH$FILL (0. 6*ITM$S_ITEM, 
ITMLST[0, ITM$W_ITMCOD] = 
ITMLST[0, ITM$W_BUFSIZ] = 
ITMLST[0, ITM$L_BUFADR] = 
ITMLST[1, ITM$W_ITMCOD] = 
ITMLST[1. ITM$W_BUFSIZ] = 
ITMLST[1, ITM$L_BUFADR] = 
ITMLST[2, ITM$W_ITMC0D] = 
ITMLST[2, ITM$W_BUFSIZ] = 
ITMLST [2, ITM$L_BUFADR] = 
1 - ACLEDIT$V_JOURNAL); 


ITMLST); 

ACLEDIT$C_OBJNAM; 

7.CHARC0UNT ( ' YOUR.OBJECT.NAME' ) ; 
$DESCRIPTOR ('YOUR.OBJECT.NAME'); 
ACLEDIT$C_OBJTYP; 

4; 

UPLIT (ACL$C_FILE); 
ACLEDIT$C_OPTIONS; 

4; 

UPLIT (1 ~ ACLEDIT$V_PROMPT_MODE OR 


RETURN ACLEDIT$EDIT (ITMLST); 
END; ! End of routine STARTUP 


END 

ELUDOM 


2.3 ACL Editor Routine 


The following pages describe the ACL Editor routine in routine template 
format. 








Access Control List (ACL) Editor Routine 

ACLEDIT$EDIT 

ACLEDIT$EDIT—Edit Access Control List 

Creates or modifies the access control list of any object in the 
system. 

FORMAT 

ACLEDIT$EDIT item-list 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return by value a condition 
value in RO. Condition values that can be returned by this routine are listed 
in "CONDITION VALUES RETURNED." 


ARGUMENT 


item-list 

VMS Usage: 
type: 
access: 
mechanism: 


item_list_3 
longword (unsigned) 
read only 
by descriptor 


Item list. The item-list argument is the address of one or more descriptors 
of arrays, routines, or longword bitmasks that control various aspects of the 
editing session. 

The item list used by the callable ACL editor is used to provide the needed 
information. Each entry in item list is in the standard format as shown in 
Figure ACL-1. 

Figure ACL-1 Item List 



ACL—3 


















Access Control List (ACL) Editor Routine 

ACLEDIT$EDIT 


Item Identifier Description 

ACLEDIT$C_OBJNAM Specifies the name of the object whose ACL is 

being edited. 

ACLEDIT$C_OBJTYP Specifies the type of the object whose ACL is being 

edited. These type codes are defined in SACLDEF. 
The default object type is a file (ACL$C_FILE). 

ACLEDIT$C_OPTIONS Represents a longword bitmask the various options 

available to control the editing session. 


Flag 

Function 

ACLEDIT$V_JOURNAL 

Indicates that the 
editing session is 
to be journaled. 

ACLEDIT$V_RECOVER 

Indicates that the 
editing section is 
to be recovered 
from an existing 
journal file. 

ACLEDIT$V_KEEP_RECOVER 

Indicates that the 
journal file used 
to recover the 
editing session 
is not to be 
deleted when 
the recovery is 
complete. 

ACLEDIT$V_KEEP_JOURNAL 

Indicates that the 
journal file used 
for the editing 
session is not to 
be deleted when 
the session ends. 

ACLEDIT$V_PROMPT_MODE 

Indicates that 
the session is to 
use automatic 
text insertion 
(prompting) to 
build new ACEs. 


ACLEDIT$C_BIT_TABLE Specifies a vector of quadword descriptors, to be 

used when parsing or formatting an ACE, which will 
be used to define the names of the bits present in 
the access mask. 


DESCRIPTION The ACLEDIT$EDIT routine is used to create and modify an ACL associated 

with any system object. 

Under normal circumstances, the application calls the ACL editor to modify 
an object's ACL, and control is returned to the application when the user 
finishes or aborts the editing session. 

You also wish to use a customized version of the ACL editor section file, 
the logical name ACLSECINI should be defined. See the VAX/VMS Access 
Control List Editor Reference Manual for more information. 
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3 Command Language (CLI) Routines 


3.1 Introduction to CLI Routines 

The CLI routines are used to process command strings using information 
from a command table. A command table contains command definitions 
that describe the allowable formats for commands. To create or modify 
a command table, you must write a command definition file and then 
process this file with the Command Definition Utility (the SET COMMAND 
command). For information on using the Command Definition Utility, see the 
VAX/VMS Command Definition Utility Reference Manual. 

The CLI routines include: 

• CLI$DCL-PARSE 

• CLI$DISPATCH 

• CLI$GET_VALUE 

• CLI$PRESENT 

When you use the Command Definition Utility to add a new command 
to your process command table or to the DCL command table, use the 
CLI$PRESENT and CLI$GET_VALUE routines in the program that is 
invoked by the new command. These routines retrieve information about 
the command string that invoked the program. 

When you use the Command Definition Utility to create an object module 
containing a command table, and you link this module with a program, 
you must use all four CLI routines. First, use CLI$DCL—PARSE and 
CLI$DISPATCH to parse command strings and invoke routines. Then, 
use CLI$PRESENT and CLI$GET_VALUE within the routines that execute 
each command. 


3.2 Example of Using the CLI Routines 

The following example contains a command definition file 
(SUBCOMMANDS.CLD) and a FORTRAN program (INCOME.FOR). 
INCOME.FOR uses the command definitions in SUBCOMMANDS.CLD to 
process commands. To execute the example, issue the following commands: 

$ SET COMMAND SUBCOMMANDS/OBJECT=SUBCOMMANDS 
$ FORTRAN INCOME 
$ LINK INCOME,SUBCOMMANDS 
$ RUN INCOME 

INCOME.FOR accepts a command string and parses it using 
CLI$DCL—PARSE. If the command string is valid, the program uses 
CLI$DISPATCH to execute the command. Each routine uses CLI$PRESENT 
and CLI$GET—VALUE to obtain information about the command string. 
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Command Language (CLI) Routines 

Example of Using the CLI Routines 


Example CLI-1 


Using the CLI Routines to Retrieve Information 
About Command Lines in a FORTRAN Program 


**************************************************** 
SUBCOMMANDS.CLD 

**************************************************** 
MODULE INCOME.SUBCOMMANDS 

DEFINE VERB ENTER 
ROUTINE ENTER 
DEFINE VERB FIX 
ROUTINE FIX 

QUALIFIER HOUSE.NUMBERS, VALUE (LIST) 

DEFINE VERB REPORT 
ROUTINE REPORT 

QUALIFIER OUTPUT, VALUE (TYPE = $FILE, 

DEFAULT = "INCOME.RPT") 
DEFAULT 

**************************************************** 
INCOME.FOR 

**************************************************** 
PROGRAM INCOME 
INTEGER STATUS, 

2 CLI$DCL_PARSE, 

2 CLI$DISPATCH 

INCLUDE '($RMSDEF)' 

INCLUDE '($STSDEF) 1 
EXTERNAL INCOME.SUBCOMMANDS, 

2 LIB$GET_INPUT 

! Write explanatory text 
STATUS = LIB$PUT_OUTPUT 
2 ('Subcommands: ENTER - FIX - REPORT') 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL (STATUS)) 
STATUS * LIBIPUT.OUTPUT 
2 ('Press CTRL/Z to exit') 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL (STATUS)) 

! Get first subcommand 

STATUS = CLI$DCL_PARSE C/.VAL (0), 

2 INCOME.SUBCOMMANDS, 

2 LIB$GET_INPUT, 

2 LIB$GET_INPUT, 

2 'INCOME> ') 




! CLD module 
! Parameter routine 
! Command routine 
! Command prompt 


(Continued on next page) 
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Command Language (CLI) Routines 

Example of Using the CLI Routines 


Example CLI-1 (Cont.) Using the CLI Routines to Retrieve 

Information About Command Lines in a 
FORTRAN Program 


! Do it until user presses CTRL/Z 
DO WHILE (STATUS .NE. RMS$_E0F) 

! If no error on dcl_parse 
IF (STATUS) THEN 

! Dispatch depending on subcommand 
STATUS = CLIIDISPATCH () 

IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS)) 


! Do not signal warning again 

ELSE IF (IBITS (STATUS, 0, 3) .NE. STS$K_WARNING) THEN 
CALL LIBISIGNAL (7.VAL (STATUS)) 

END IF 

! Get another subcommand 


STATUS = 

* CLIIDCL.PARSE 

(7.VAL (0), 


2 


INCOME.SUBCOMMANDS. 

! CLD module 

2 


LIBlGET.INPUT, 

! Parameter routine 

2 


LIBIGET.INPUT, 

! Command routine 

2 

END DO 

END 


'INC0ME> ') 

! Command prompt 

INTEGER 
INCLUDE 
TYPE *, 
ENTER = 
END 

FUNCTION ENTER 
'(ISSDEF)' 
'ENTER invoked' 
SSI.NORMAL 

0 



INTEGER FUNCTION FIX () 
INTEGER STATUS, 

2 CLIlPRESENT, 

2 CLI$GET_VALUE 

CHARACTER*15 HOUSE.NUMBER 
INTEGER*2 HN.SIZE 
INCLUDE 1 (ISSDEF) 1 
EXTERNAL CLII.ABSENT 


TYPE *, 'FIX invoked' 

! If user types /house_numbers=(n,...) 

IF (CLIlPRESENT ('HOUSE.NUMBERS')) THEN 
! Get first value for /house_numbers 
STATUS = CLI$GET_VALUE ('HOUSE.NUMBERS', 
2 HOUSE.NUMBER, 

2 HN.SIZE) 


! Do it until the list is depleted 
DO WHILE (STATUS) 

TYPE *, 'House number = ', HOUSE.NUMBER (1:HN_SIZE) 
STATUS = CLIIGET.VALUE ('HOUSE.NUMBERS*, 

2 HOUSE.NUMBER, 

2 HN.SIZE) 

END DO 

! Make sure termination status was correct 
IF (STATUS .NE. %L0C (CLII.ABSENT)) THEN 
CALL LIBISIGNAL (%VAL (STATUS)) 

END IF 
END IF 

FIX = SSI.NORMAL 
END 


(Continued on next page) 
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Example of Using the CLI Routines 


Example CLI-1 (Cont.) Using the CLI Routines to Retrieve 

Information About Command Lines in a 
FORTRAN Program 


INTEGER FUNCTION REPORT () 

INTEGER STATUS. 

2 CLI$GET_VALUE 

CHARACTER*64 FILENAME 
INTEGER*2 FN.SIZE 

INCLUDE '($SSDEF)' 

TYPE *, 'REPORT entered' 

! Get value for /output 

STATUS = CLIlGET.VALUE ('OUTPUT', 

2 FILENAME. 

2 FN.SIZE) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL (STATUS)) 
TYPE *. 'Output file: '. FILENAME (IrFN.SIZE) 
REPORT = SSI.NORMAL 
END 


3.3 CLI Routines 


The following pages describe the individual CLI routines in routine template 
format. 
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Command Language (CLI) Routines 

CLI$DCI_PARSE 

CLI$DCI_ 

-PARSE—Parse DCL Command 
String 

Routine parses a command string using the command definition 
supplied in the specified command table. 

FORMAT 

CLI$DCI_PARSE command-string ,table 

[,param-routine] [,prompt-routine] 
[, prompt-string] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

command-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor-fixed length 

Character string containing the command to be parsed. The 
command—string argument is the address of a descriptor specifying the 
command string to be parsed. If the command string includes a comment 
(delimited by an exclamation mark) DCL ignores the comment. 

If the command string contains a hyphen to indicate that the string is being 
continued, DCL uses the routine specified in the prompt-routine argument to 
obtain the rest of the string. The command string is limited to 256 characters. 
However, if the string is continued with a hyphen, CLI$DCL—PARSE can 
prompt for additional input until the total number of characters is 1024. 

If you specify the command-string argument as zero and you also specify 
a prompt routine, then DCL will prompt for the entire command string. 
However if you specify the command-string argument as zero and you also 
specify the prompt-routine argument as zero, then DCL will restore the parse 
state of the command string that originally invoked the image. 

CLI$DCL_PARSE does not perform DCL-style symbol substitution on the 
command string. 
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CLISDCL. 

-PARSE 


table 

VMS Usage: char_string 
type: unspecified 

access: read only 

mechanism: by reference 

Name of the module containing the command language description. The 
table argument is the address of the command table that describes the syntax 
by which the command line should be parsed. This is usually represented by 
a global symbol that is created by the Command Definition Utility when it 
processes the MODULE statement in the command definition file. 

The command table is created with the DCL command SET COMMAND 
/OBJECT, and is linked with your image. 

param-routine 

VMS Usage: procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

Name of a routine to obtain a required parameter not supplied in the 
command text. The param-routine argument is the address of a routine 
containing a required parameter that was not specified in the command¬ 
string argument. 

To specify the parameter routine, use the address of LIB$GET_INPUT or the 
address of a routine of your own that has the same three-argument calling 
format as LIB$GET_INPUT. See the description of LIB$GET_INPUT in the 
VAX/VMS Run-Time Library Routines Reference Manual for information about 
the calling format. The status returned by LIB$GET_INPUT must be success 
or the CLI$DCL—PARSE routine exits and propagates the error outward. 

The prompt string for a required parameter is obtained from the command 
table specified in the table argument. 

prompt-routine 

VMS Usage: procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

Name of a routine to obtain all or part of the text of a command. The 
prompt-routine argument is the address of a routine to obtain the text or 
the remaining text of the command depending on the command-string 
argument. DCL uses this routine to obtain an entire command line if a zero 
is specified in the command-string argument. DCL uses this routine to 
obtain a continued command line if the command string (obtained from the 
command-string argument) contains a hyphen to indicate that the string is 
being continued. 

To specify the prompt routine, use the address of LIB$GET_INPUT or the 
address of a routine of your own that has the same three-argument calling 
format as LIB$GET_INPUT. See the description of LIB$GET_INPUT in the 
VAX/VMS Run-Time Library Routines Reference Manual for information about 
the calling format. The status returned by LIB$GET_INPUT must be success 
or the CLI$DCL_PARSE routine exits and propagates the error outward. 
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CLI$DCI_PARSE 



prompt-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Character string containing a prompt. The prompt-string argument is the 
address of a string descriptor pointing to the prompt string to be passed as 
the second argument to the prompt-routine argument. 

If DCL is using the prompt routine to obtain a continuation line, DCL inserts 
an underscore character before the first character of the prompt string to 
create the continuation prompt. If DCL is using the prompt routine to obtain 
an entire command line (that is, a zero was specified as the command-string 
argument), DCL uses the prompt string exactly as specified. 

The prompt string is limited to 32 characters. The string "COMMAND> " is 
the default prompt string. 

DESCRIPTION 

The CLI$DCL_JPARSE routine supplies a command string to DCL for parsing. 
DCL parses the command string according to the syntax in the command table 
specified in the table argument. 

The CLI$DCL—PARSE routine can prompt for required parameters if you 
specify a parameter routine in the routine call. In addition, the 

CLI$DCL —PARSE routine can prompt for entire or continued command lines 
if you supply the address of a prompt routine. 

If a CTRL/Z is entered or if RMS$_EOF is returned as a response to any 
prompt, CLI$DCL_PARSE immediately terminates and returns the status 
RMS$_EOF. If a null string is entered in response to a prompt for an entire or 
a continued command string (specified with the prompt-routine argument), 
CLI$DCL_PARSE terminates and returns the status CLI$_NOCOMD. If 
a null string is entered in reponse to a prompt for a required parameter, 
CLI$DCL_PARSE reissues the prompt. 

Whenever CLI$DCL—PARSE encounters an error, it both signals and returns 
the error. 

CONDITION 

VALUES 

RETURNED 

CLI$_NORMAL Normal successful completion 

CLI$_NOCOMD A null string was entered in response to a prompt 

from the prompt-routine argument. This causes 
the CLI$DCL_PARSE routine to terminate. 

RMSS—EOF A CTRL/Z was entered in response to a prompt. 

This causes the CLI$DCL_PARSE routine to 


terminate 
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CLI$DISPATCH 


CLI$DISPATCH—Dispatch to Action 



Routine 

Invokes the subroutine associated with the verb most recently 
parsed by a CLI$DCL_PARSE routine call. 

FORMAT 

CLISDISPATCH [userarg] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

userarg 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Data passed to the action routine. The userarg argument is a longword that 
contains the data passed by the action routine. This data can be used in any 
way that you want. 

DESCRIPTION 

The CLI$DISPATCH routine invokes the subroutine associated with the verb 
most recently parsed by a CLI$DCL _PARSE routine call. If the routine is 
successfully invoked, the return status is the status returned by the action 
routine. Otherwise, a status of CLI$_INVROUT is returned. 

CONDITION 

VALUES 

RETURNED 

CLI$_INVROUT CLI$DISPATCH is unable to invoke the routine 

because an invalid routine is specified in the 
command table, or no routine is specified. 
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CLI$GET_VALUE 


CLI$GET_VALUE—Get Value of Entity in 



Command String 

Retrieves the value associated with a specified qualifier, parameter, 
or keyword path. 

FORMAT 

CLI$GET_VALUE entity-desc ,retdesc[,retlength] 

RETURNS 

VMS Usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

entity—desc 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Character string containing the label (or name if no label is defined) of the 
entity. The entity-desc argument is the address of a string descriptor that 
points to an entity that may appear on a command line. The entity_desc 
argument can be expressed as: 

• a parameter, qualifier, or keyword name or label 

• a keyword path 

The entity_desc argument can contain qualifier, parameter, or keyword 
names, or can contain labels that were assigned with the LABEL clause in the 
command definition file. If the LABEL clause was used to assign a label to an 
entity, you must specify the label in the entity-desc argument. Otherwise, 
use the name of the entity. 

A keyword path is used to reference keywords that may be used as values of 
parameters, qualifiers, or other keywords. A keyword path contains a list of 
entity names or labels that are separated by periods. If the LABEL clause was 
used to assign a label to an entity, you must specify the label in the keyword 
path. Otherwise, you must use the name of the entity. 

The following command string illustrates a situation where keyword paths 
are needed to uniquely identify keywords. In this command string, you can 
use the same keywords with more than one qualifier. (This is defined in the 
command definition file by having two qualifiers refer to the same DEFINE 
TYPE statement.) 

$ NEWC0MMAND/QUAL1=(START=5.END=10)/QUAL2=(START=2,END=5) 
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CLI$GET_VALUE 


The keyword path QUAL1.START identifies the START keyword when it is 
used with QUAL1; the keyword path QUAL2.START identifies the keyword 
START when it is used with QUAL2. The name START is an ambiguous 
reference if used alone. 

Keywords that are not needed to unambiguously resolve a keyword reference 
can be omitted from the beginning of a keyword path. The path can be no 
more than eight names long. 

If you use an ambiguous keyword reference, DCL resolves the reference by 
checking, in the following order: 

1 The parameters in your command definition file, in the order they are 
listed 

2 The qualifiers in your command definition file, in the order they are listed 

3 The keyword paths for each parameter, in the order the parameters are 
listed 

4 The keyword paths for each qualifier, in the order the qualifiers are listed 

DCL uses the first occurrence of the entity as the keyword path. Note that 
DCL does not issue an error message if you provide an ambiguous keyword. 
However, you should never use ambiguous keyword references because the 
keyword search order may change in future releases of VAX/VMS. 

If the entity_desc argument does not exist in the command table, 
CLI$GET_VALUE will signal a syntax error (via the signaling mechanism 
described in the VAX/VMS Run-Time Library Routines Reference Manual. 


retdesc 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
write only 
by descriptor 


Character string containing the value retrieved by CLI$GET_VALUE. The 
retdesc argument is the address of a string descriptor pointing to the buffer to 
receive the string value retrieved by CLI$GET_VALUE. The string is returned 
using the STR$COPY_DX VAX-11 Run-Time Library routine. 

If there are errors in the specification of the return descriptor or in copying 
the results using that descriptor, the STR$COPY_DX routine will signal the 
errors. For a list of these errors, see the VAX/VMS Run-Time Library Routines 
Reference Manual. 


retlength 


VMS Usage: 
type: 
access: 
mechanism: 


word-unsigned 
word (unsigned) 
write only 
by reference 


Word containing the number of characters DCL returned to RETDESC. The 
retlength argument is the address of the word containing the length of the 
retrieved value. 
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CLI$GET_VALUE 


DESCRIPTION The CLI$GET_VALUE retrieves a value associated with a specified qualifier, 

parameter, keyword, or keyword path from the parsed command string. 

You can use the following label names with CLI$GET_VALUE to retrieve 
special strings: 

$VERB Describes the verb in the command string (the first four letters of the 
spelling as defined in the command table, instead of the string that 
was actually typed). 

$LINE Describes the entire command string as stored internally by DCL. In 

the internal representation of the command string, multiple spaces and 
tabs are removed, alphabetic characters are converted to uppercase, 
and comments are stripped. Integers are converted to decimal. If 
dates and times were specified in the command string, DCL fills in any 
defaulted fields. Also, if date-time strings (such as YESTERDAY) were 
used, DCL substitutes the corresponding absolute time value. 

To obtain the values for a list of entities, call CLI$GET_VALUE repeatedly 
until all values have been returned. After each CLI$GET_VALUE call, the 
returned condition value will indicate whether there are more values to be 
obtained. You should call CLI$GET_VALUE until you receive a condition 
value of CLI$_ABSENT. 

When you are using CLI$GET_VALUE to obtain a list of qualifier or keyword 
values, you should get all values in the list before starting to parse the next 
entity. 


CONDITION CLI$_COMMA 

VALUES 

RETURNED cli$_concat 

SS$_NORMAL 


CLIS—ABSENT 


The returned value is terminated by a comma; this 
shows there are additional values in the list. 

The returned value is concatenated to the next 
value with a plus sign; this shows there are 
additional values in the list. 

The returned value is terminated by a blank or an 
end-of-line; this shows that the value is the last, or 
only, value in the list 

The value is not present, or the last value in the 
list was already returned. 
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CLI$PRESENT 


CLI$PRESEIMT—Determine Presence of 

Entity in Command String 


Determines whether a parameter, qualifier, or keyword is present in 
the command string. 

FORMAT 

CLI$PRESENT entity—desc 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 


ARGUMENT 


entity— desc 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Character string containing the label (or name if no label is defined) of the 
entity. The entity-desc argument is the address of a string descriptor that 
points to an entity that may appear on a command line. An entity can be 
expressed as: 

• a parameter, qualifier, or keyword name or label 

• a keyword path 


A keyword path is used to reference keywords that are accepted by 
parameters, qualifiers, or other keywords. A keyword path contains a list 
of entity names separated by periods. See the description of the entity_desc 
argument in the CLI$GET_VALUE routine for more information on specifying 
keyword paths as arguments for CLI routines. 

The entity_desc argument can contain parameter, qualifier, or keyword 
names, or can contain labels that were assigned with the LABEL clause in the 
command definition file. If the LABEL clause was used to assign a label to a 
qualifier, parameter, or keyword, you must specify the label in the 
entity_desc argument. Otherwise, you must use the actual name of the 
qualifier, parameter, or keyword. 

If the entity_desc argument does not exist in the command table, 
CLI$PRESENT will signal a syntax error (via the signaling mechanism 
described in the VAX/VMS Run-Time Library Routines Reference Manual). 
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CLI$PRESENT 


DESCRIPTION The CLI$PRESENT routine examines the parsed command string to determine 

whether the entity referred to by the entity_desc argument is present. 

When CLI$PRESENT tests whether a qualifier is present, the condition 
value indicates whether the qualifier is used globally or locally. A global 
qualifier can be used anywhere in the command line; a local qualifier must 
be used after a parameter. A global qualifier is defined in the command 
definition file with PLACEMENT=GLOBAL; a local qualifier is defined with 
PLACEMENT=LOCAL. 

When you test for the presence of a global qualifier, CLI$PRESENT 
determines if the qualifier is present anywhere in the command string. If 
the qualifier is present in its positive form, CLI$PRESENT returns 
CLI$_PRESENT; if the qualifier is present in its negative form, CLI$PRESENT 
returns CLI$_NEGATED. 

You can test for the presence of a local qualifier when you are parsing 
parameters that the qualifier can be specified after. After you call 
CLI$GET_VALUE to fetch the parameter value, call CLI$PRESENT to 
determine whether the local qualifier is present. If the local qualifier is 
present in its positive form, CLI$PRESENT returns CLI$_LOCPRES; if the 
local qualifier is present in its negative form, CLI$PRESENT returns 
CLI$_ LOCNEG. 

A positional qualifier affects the entire command line if it appears after the 
verb but before the first parameter. A positional qualifier affects a single 
parameter if it appears after a parameter. A positional qualifier is defined in 
the command definition file with the PLACEMENT=POSITIONAL clause. 

To determine whether a positional qualifier is used globally, call 
CLI$PRESENT to test for the qualifier before you call CLI$GET_VALUE 
to fetch any parameter values. If the positional qualifier is used globally, 
CLI$PRESENT returns either CLI$_PRESENT or CLI$_NEGATED. 

To determine whether a positional qualifier is used locally, call CLI$PRESENT 
immediately after a parameter value has been fetched by CLI$GET_VALUE. 
The most recent CLI$GET_VALUE call to fetch a parameter defines the 
context for a qualifier search. Therefore, CLI$PRESENT will test whether a 
positional qualifier was specified after the parameter that was fetched by the 
most recent CLI$GET_VALUE call. If the positional qualifier is used locally, 
CLI$PRESENT returns either CLI$_LOCPRES or CLI$_JLOCNEG. 


CONDITION CLI$_PRESENT 

VALUES 

RETURNED 

CLI$_NEGATED 

CLI$_LOCPRES 


The specified entity was present in the command 
string. This status is returned for all entities except 
local qualifiers and positional qualifiers that are 
used locally. 

The specified qualifier was present in its negated 
form (with /NO) and was used as a global qualifier. 

The specified qualifier was present and was used 
as a local qualifier. 
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CLI$PRESENT 


CLI$_LOCNEG 

CLI$_DEFAULTED 

CLI$_ABSENT 


The specified qualifier was present in its negated 
form (with /NO) and was used as a local qualifier. 

The specified entity was not present but there is a 
default value. 

The specified entity was not present and there is 
no default value. 
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4 Convert (CONV) Routines 


4.1 Introduction to Convert Routines 

This section describes the Convert Routines. These routines perform the 
functions of both the VAX RMS Convert and Convert/Reclaim Utilities. 

The Convert Utility copies records from one or more files to an output file, 
changing the record format and file organization to that of the output file. 
You can invoke the functions of the Convert Utility from within a program by 
calling this series of three routines. 

1 CONV$PASS_FILES 

2 CONV$PASS_OPTIONS 

3 CONV$CONVERT 

The routines must be called in this order. 

The Convert/Reclaim Utility reclaims empty buckets in Prolog 3 indexed 
files so that new records can be written in them. You can invoke the 
functions of the Convert/Reclaim Utility from within a program by calling 
the CONV$RECLAIM Routine. 

These routines cannot be called from AST level. 


4.2 Examples of Using the CONV Routines 

The following example shows how to use the Convert routines in a 
FORTRAN program. 
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Convert (CONV) Routines 

Examples of Using the CONV Routines 


Example CONV-1 Using the CONVERT Routines in a FORTRAN 

Program 


* This program calls the routines that perform the 

* functions of the Convert Utility. It creates an 

* indexed output file named CUSTDATA.DAT from the 

* specifications in an FDL file named INDEXED.FDL. 

* The program then loads CUSTDATA.DAT with records 

* from the sequential file SEQ.DAT. No exception 

* file is created. This program also returns all 

* the CONVERT statistics. 


* Program declarations 

IMPLICIT INTEGERS (A - Z) 

* Set up parameter list: number of options, CREATE, 

* NOSHARE, FAST.LOAD, MERGE, APPEND, SORT, WORK.FILES, 

* KEY=0, NOPAD, PAD CHARACTER, NOTRUNCATE, 

* NOEXIT, NOFIXED.CONTROL, FILL.BUCKETS. NOREAD.CHECK, 

* NOWRITE_CHECK, FDL, and NOEXCEPTION. 

* 

INTEGER*4 OPTIONS(19), 

1 /18,1,0,1,0,0,1,2,0,0,0,0,0,0,0,0,0,1,0/ 

* Set up statistics list. Pass an array with the 

* number of statistics that you want. There are four 

* - number of files, number of records, exception 

* records, and good records, in that order. 

INTEGER*4 STATSBLK(5) /4,0,0,0.0/ 

* Declare the file names. 

CHARACTER IN_FILE*7 /•SEQ.DAT'/, 

1 0UT_FILE*12 /'CUSTDATA.DAT'/, 

1 FDL_FILE*11 /'INDEXED.FDL'/ 

* Call the routines in their required order. 

STATUS = CONV$PASS_FILES (IN.FILE, OUT.FILE, FDL_FILE) 

IF (.NOT. STATUS) CALL LIB$ST0P (7.VAL(STATUS)) 

STATUS = C0NV$PASS_0PTI0NS (OPTIONS) 

IF (.NOT. STATUS) CALL LIB$ST0P (7.VAL(STATUS)) 

STATUS = C0NV$C0NVERT (STATSBLK) 

IF (.NOT. STATUS) CALL LIB$ST0P (7.VAL(STATUS)) 

* Display the statistics information. 

WRITE (6,1000) (STATSBLK(I),1*2,5) 

1000 FORMAT (IX,'Number of files processed: '.15/, 

1 IX,'Number of records: ',15/, 

1 IX,'Number of exception records: ',15/, 

1 IX,'Number of valid records: ',15) 

END 


The following example shows how to use the Convert routines in a MACRO 
program. 
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Example CONV-2 Using the CONVERT Routines in a MACRO 

Program 


.TITLE CONVSTAT.MAR 

This module calls the routines that perform the functions 
of the Convert Utility. It creates an indexed output file 
named CUSTDATA.DAT from the specifications in am FDL file 
named INDEXED.FDL, and loads CUSTDATA.DAT with records from 
the sequential file SEQ.DAT. No exception file is created. 


; This module 

also returns 

all the CONVERT statistics. 

; Declare the 

file names. 



FILEIN: 

.ASCID 


/SEQ.DAT/ 

FILEOUT: 

.ASCID 


/CUSTDATA.DAT/ 

FDLFILE: 

.ASCID 


/INDEXED.FDL/ 

; Set up parameter list. 



PARAM_LIST: 

.LONG 

18 


NUMBER OF LONGWORDS FOLLOWING 


.LONG 

1 


CREATE 


.LONG 

0 


NOSHARE 


.LONG 

1 


FAST.LOAD 


.LONG 

0 


MERGE 


.LONG 

0 


APPEND 


.LONG 

1 


SORT 


.LONG 

2 


WORK.FILES 


.LONG 

0 


KEY=0 


.LONG 

0 


NOPAD 


.LONG 

0 


PAD CHARACTER 


.LONG 

0 


NOTRUNCATE 


.LONG 

0 


NOEXIT 


.LONG 

0 


NOFIXED.CONTROL 


.LONG 

0 


FILL_BUCKETS 


.LONG 

0 


NOREAD.CHECK 


.LONG 

0 


NOWRITE.CHECK 


.LONG 

1 


FDL 


.LONG 

0 


NOEXCEPTION 

; Have to use 

Formatted ASCII 

Output (FAO) conversion 

; Declare FAO 

info for 

statistics 

FAO.DESC: 

.LONG 


132 


.LONG 


FAO.BUFFER 

FAO_BUFFER: 

.BLKB 


132 

FAO.LEN: 

. BLKL 


1 

L 

OUTSTUFF: 

.ASCID 


#Number of files processed: SUL !/- 


Number of records: SUL !/- 

Number of exception records: SUL !/- 

Number of valid records: SUL !/# 


(Continued on next page) 
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Example CONV-2 (Cont.) Using the CONVERT Routines in a 

MACRO Program 


Have to pass a longword to the CONV$CONVERT ROUTINE with the 
number of statistics that we want. There are 4 -- number of 
files, number of records, exception records, good records, 
in that order. 


STATSBLK: 

.LONG 4 

;The value 4 is the number of statistics 
;that we want, we pass this value to 



;the END.CONVERT routine. 

STATS: 

.BLKL 4 

;Where we place the statistics. This block 
;must follow the longword that tells how 



;many stats we want. 

TIMES: 

.BLKL 5 

;Where we place the timing info. 


Declare the external routines. 


.EXTRN CONV$PASS_FILES,CONV$PASS_OPTIONS.CONV$CONVERT,- 
LIB$PUT_OUTPUT,LIB$INIT_TIMER,LIB$SYS_FAOL 

.ENTRY CONV,~M<R2,R3,R4,R5,R6,R7> ;SAVE THOSE REGISTERS; 

Perform operations. Push addresses on arg stack, call routines. 


PUSHAL 

TIMES 


CALLS 

#i,G~LIB$INIT_TIMER 

;Start the timer 

PUSHAL 

FDLFILE 


PUSHAL 

FILEOUT 


PUSHAL 

FILEIN 

;Push filenames on arg stack 

CALLS 

#3,G~CONV$PASS_FILES 

;Pass filenames 

BLBC 

RO,10$ 


PUSHAL 

PARAM.LIST 

;Push parameter list 

CALLS 

#1,G~C0NV$PASS_0PTI0NS 

;Make the second call 

BLBC 

RO,10$ 


PUSHAL 

STATSBLK 

;Pu8h address of the number of 
;Statistics 

CALLS 

#1,G~C0NV$C0NVERT 

;Perform conversion 

BLBC 

RO,10$ 


need an 

FAO routine to format the 

count8 

$FAOL_S 

CTRSTR=OUTSTUFF,0UTLEN=FA0_LEN,0UTBUF=FA0_DESC,- 
PRMLST=STATS 

BLBC 

RO,10$ 


PUSHAL 

FAO.DESC 

;Push output buffer on stack 

CALLS 

#1,G~LIB$PUT_OUTPUT 

;Send the output buffer to 
;SYS$0UTPUT 

BLBC 

RO,10$ 



(Continued on next page) 
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Example CONV-2 (Cont.) Using the CONVERT Routines in a 

MACRO Program 


Display times 


PUSHAL 

TIMES 

CALLS 

#1,G~LIB$SHOW_TIMER 

BLBC 

RO,10$ 

MOVL 

#SS$_N0RMAL,RO 

RET 

.END 

CONV 


The following example shows how to use the CONV$RECLAIM routine in a 
FORTRAN program. 


Example CONV-3 Using the CONVERT/RECLAIM Routine in a 

FORTRAN Program 


* This program calls the routine that performs the 

* function of the Convert/Reclaim Utility. It 

* reclaims empty buckets from an indexed file named 

* PR0L3.DAT. It also returns all the CONVERT/RECLAIM 

* statistics. 

* Program declarations 

IMPLICIT INTEGER*4 (A - Z) 

* Set up a statistics block. There are four - data 

* buckets scanned, data buckets reclaimed, index 

* buckets reclaimed, total buckets reclaimed. 

INTEGER*4 0UTSTATS(5) /4,0,0,0,0/ 

* Declare the input file. 

CHARACTER IN_FILE*9 /'PR0L3.DAT'/ 

* Call the routine. 

STATUS * CONV$RECLAIM (IN.FILE, OUTSTATS) 

IF (.NOT. STATUS) CALL LIB$ST0P (7,VAL(STATUS)) 

* Display the statistics. 

WRITE (6,1000) (OUTSTATS(I).1=2,5) 

1000 FORMAT (lX.'Number of data buckets scanned: ',15/, 

1 lX.'Number of data buckets reclaimed: ',15/, 

1 lX.'Number of index buckets reclaimed: ',15/, 

1 IX,'Total buckets reclaimed: ',15) 

END 


The following example shows how to use the CONV$RECLAIM routine in a 
MACRO program. 
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Example CONV-4 Using the CONVERT/RECLAIM Routine in a 

MACRO Program 


.TITLE CONVREC.MAR 


This module calls the routine that performs the 
function of the CONVERT/RECLAIM Utility. It reclaims 
empty buckets from an indexed file named PR0L3.DAT. 

This module also returns all of the CONVERT/RECLAIM 
statistics. 


Declare the file name. 


FILEIN: 

.ASCID 

/PR0L3.DAT/ 

; Declare 

statistics blocks 

OUTSTATS: 

.LONG 

4 


.BLKL 

4 

; Declare 

FAO info for 

statistics 

FAO.DESC: 

.LONG 

132 


.LONG 

FAO.BUFFER 

FAO.BUFFER 

. BLKB 

132 

FAO.LEN: 

.BLKL 

1 

OUTSTUFF: 

.ASCID 

#Data buckets scanned: !UL !/- 

Data buckets reclaimed: 

!UL !/- 


Index buckets reclaimed: !UL !/- 
Total buckets reclaimed: !UL !/# 

; Looking for four statistics back from the end call. 
; Use FAO conversion. 

; Declare the external routines. 

.EXTRN CONV$RECLAIM,LIB$PUT_OUTPUT 

.ENTRY CONV,~M<> 


Perform operations. Push addresses on arg stack, call 
routines. 

PUSHAL OUTSTATS 

PUSHAL FILEIN ;PUSH FILENAME ON ARG STACK 

CALLS #2,G~CONV$RECLAIM ;PASS FILENAME 

BLBC RO,10$ 


(Continued on next page) 
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Example CONV-4 (Cont.) Using the CONVERT/RECLAIM 

Routine in a MACRO Program 


Now need an FAQ routine to format the counts. 


$FA0L_S 

CTRSTR=OUTSTUFF,OUTLEN= 
PRMLST=0UTSTATS+4 

=FA0_LEN,0UTBUF=FA0_DESC,- 

BLBC 

RO,10$ 


PUSHAL 

FAO.DESC 

;PUSH OUTPUT BUFFER ON STACK 

CALLS 

#1 ,G~LIB$PUT_OUTPUT 

;SEND THE OUTPUT BUFFER TO 
;SYS$OUTPUT 

BLBC 

RO,10$ 


MOVL 

#SS$_N0RMAL,RO 


RET 




.END CONV 


4.3 CONV Routines 


The following pages describe the individual Convert routines in routine 
template format. 
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CON V$CON VERT—Initiate Conversion 



Invokes the Convert Utility to copy records from one or more 
source data files to a second output data file, which can differ in 
file organization and format from the first. The routine can also 
return statistics about the conversion. 

FORMAT 

CONVSCONVERT [status-block-address][.flags] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

status-block-address 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

The conversion statistics. The status-block-address argument is the address 
of a variable-length array of longwords that receives statistics about the 
conversion. The format of the array is shown below: 

number of statistics 
number of files 
number of records 
number of exception records 
number of valid records 

flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Flags (or masks) that control how the fdl-file-spec argument is interpreted 
and how errors are signalled. The flags argument is the address of a 
longword containing control flags (or a mask). If the flags argument is 
omitted or is specified as zero, no flags are set. The flags and their meanings 
are described below. 
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CONV$CONVERT 



Flag 

Function 


CONV$V_FDL_STRING 

Interprets the fdl-file_spec argument supplied in the 
call to CONV$PASS_FILES as an FDL specification in 
string form. By default, this argument is interpreted 
as a file name of an FDL file. 


CONV$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 


signalled. 


DESCRIPTION 

The CONV$CONVERT routine uses the Convert Utility to perform the actual 
conversion begun with CONV$PASS_FILES and CONV$PASS_OPTIONS. 
Optionally, the routine can return statistics about the conversion. 

CONDITION 

SSS—NORMAL 

Normal successful completion. 

VALUES 

CONV$_BADBLK 

Invalid option block. 

RETURNED 

CONV$_BADLOGIC 

Internal logic error detected. 


CONVS—BADSORT 

Error trying to sort input file. 


CONV$_CLOSEIN 

Error closing file specification as input. 


CONV$_CLOSEOUT 

Error closing file specification as output. 


CONVS—CONFQUAL 

Conflicting qualifiers. 


CONV$_CREA_ERR 

Error creating output file. 


CONV$_CREATEDSTM 

File specification has been created in stream 
format. 


CONV$_DELPRI 

Cannot delete primary key. 


CONV$_DUP 

Duplicate key encountered. 


CONV$_EXTN_ERR 

Unable to extend output file. 


CONV$_F AT ALEXC 

Fatal exception encountered. 


CONV$_FILLIM 

Exceeded open file limit. 


CONV$_IDX_LIM 

Exceeded maximum index level. 


CON V$_ILL _KEY 

Illegal key or value out of range. 


CONVS—INR_FILES 

Too many input files. 


CONV$_INSVIRMEM 

Insufficient virtual memory. 


CONVS—KEY 

Invalid record key. 


CONVS—LOADIDX 

Error loading secondary index n. 


CONV$_NARG 

Wrong number of arguments. 


CONVS—NOKEY 

No such key. 


CONVS—NOTIDX 

File is not an indexed file. 


CONVS—NOTSEQ 

Output file is not a sequential file. 


CONVS—NOWILD 

No wildcard permitted. 


CONVS—OPENEXC 

Error opening exception file specification. 


CONVS—OPENIN 

Error opening file specification as input. 
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CONV$_OPENOUT 

CONV$_ORDER 

CONV$_PAD 

Error opening file specification as output. 

Routine called out of order. 

PAD option ignored, output record format 
not fixed. 

CONV$_PROERR 

CONV$_PROI_WRT 

CONV$_READERR 

CONV$_REX 

CONV$_RMS 

CONV$_RSK 

CONV$_RSZ 

CONV$_RTL 

CONV$_RTS 

CONV$_SEQ 

CONV$_UDF_BKS 

CONV$_UDF_BLK 

CONV$_VALERR 

CONV$_VFC 

CONV$_WRITEERR 

Error reading prolog. 

Prolog write error. 

Error reading file specification. 

Record already exists. 

Record caused RMS severe error. 

Record shorter than primary key. 

Record will not fit in block/bucket. 

Record longer than maximum record length. 

Record too short for fixed record format file. 

Record not in order. 

Cannot convert UDF records into spanned file. 

Cannot fit UDF records into single block bucket. 

Specified value is out of legal range. 

Record too short to fill fixed part of VFC record. 

Error writing file specification. 
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CONV$PASS_FILES 


COIMV$PASS_FILES—Specify Conversion 

Files 



Specifies the files on which CONVERT will operate. 

FORMAT 

CONV$PASS_FILES input-file-spec 

, output-file-spec [, fdl-file-spec] 
[, exception-file-spec] [, flags] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

input- file-spec 

VMS Usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor-fixed length string descriptor 

The name of the file to be converted. The input-file-spec argument is the 
address of a string descriptor pointing to the name of the file to be converted. 

output-file-spec 

VMS Usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor-fixed length string descriptor 

The name of the file that receives the records from the input file. The output- 
file-spec argument is the address of a string descriptor pointing to the name 
of the file that receives the records from the input file. 

fdl-file-spec 

VMS Usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor-fixed length string descriptor 

The name of the FDL file that defines the output file. The fdl-file-spec 
argument is the address of a string descriptor pointing to the name of the 

FDL file. 
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DESCRIPTION 


exception-file-spec 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 
read only 

by descriptor-fixed length string descriptor 


The name of the file that receives copies of records that cannot be written to 
the output file. The exception-file-spec argument is the address of a string 
descriptor pointing to this name. 


flags 

VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


Flags (or masks) that control how the fdl-file-spec argument is interpreted and 
how errors are signalled. The flags argument is the address of a longword 
containing the control flags (or mask). If this argument is omitted or is 
specified as zero, no flags are set. If you specify a flag, it remains in effect 
until you explicitly reset it in a subsequent call to a Convert routine. 

The flags and their meanings are described in the following table. 


Flag 

Function 

CON V$ V_FDL _STRI NG 

Interprets the fdl-file-spec argument as an FDL 
specification in string form. By default, this argument 
is interpreted as a file name of an FDL file. 

CONV$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 

This argument is optional, 
signalled. 

By default, an error status is returned rather than 


The CONV$PASS_FILES routine specifies a file to be converted using the 
CONV$CONVERT Routine. A single call to CONV$PASS_FILES allows 
you to specify an input file, an output file, an FDL file, and an exception file. 
If you have multiple input files, you must call CONV$PASS_FILES once 
for each file. You need to specify only the input-file-spec argument for the 
additional files, as follows: 

status = CONV$PASSJFILES (input-file-spec) 

The additional calls must immediately follow the original call that specified 
the output file specification. You may specify as many as 9 additional files for 
a maximum total of 10. 

Wildcard characters are not allowed in the file specifications passed to the 
CONVERT routines. 
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CONDITION 

VALUES 

RETURNED 



SS$_NORMAL 

CONV$_INP_FILES 

CONV$_INSVIRMEM 

CONV$_NARG 

CONV$_ORDER 


Normal successful completion. 
Too many input files. 
Insufficient virtual memory. 
Wrong number of arguments. 
Routine called out of order. 
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CON V$PASS—.OPTIONS—Specify 

Processing 

Options 



Specifies the CONVERT qualifiers to be used. 

FORMAT 

CONV$PASS—OPTIONS [parameter-list-address] 

[, flags] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

parameter-list-address 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

A parameter list specifying information about the CONVERT qualifiers. The 
parameter-list-address argument is the address of a variable-length array 
of longwords. The first longword in the array is the number of parameters 
in the array. Each following longword in the array (from the second one 
on) is associated with one of the CONVERT qualifiers. These functions are 
described in the VAX/VMS Convert and Convert/Reclaim Utility Reference 
Manual. 

To set one of the CONVERT qualifiers, you place a 1 in the longword 
associated with that qualifier. If you do not want to set one of the qualifiers 
(which has the same effect as using the form /NOQUALIFIER on the 
CONVERT command), you place a 0 in the correct longword. 

If you do not specify parameter-list-address, then the default values shown 
below apply. You can also take all default values by passing the address of a 
longword that contains 0 , which means a parameter list of 0 longwords. 

If you have specified all the values you want set, you may wish to take the 
default values for all subsequent qualifiers in the list. You may omit the 
subsequent ones if you give the array length in the first longword. This 
reason is why the first longword contains a count of the qualifiers. 

The qualifiers must appear in the following order. 
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Qualifier 

Default Value 
(in Longwords) 

Default CONVERT 

Value 

CREATE 

1 

/CREATE 

SHARE 

0 

/NOSHARE 

FAST_LOAD 

1 

/FAST_LOAD 

MERGE 

0 

/NOMERGE 

APPEND 

0 

/NOAPPEND 

SORT 

1 

/SORT 

WORK—FILES 

2 

/WORK—FILES=2 

KEY 

0 

/KEY=0 

PAD 

0 

/NOPAD 

pad character 

0 

pad character^) 

TRUNCATE 

0 

/NOTRUNCATE 

EXIT 

0 

/NOEXIT 

FIXED_CONTROL 

0 

/NOFIXED—CONTROL 

FILL—BUCKETS 

0 

/NOFILL -BUCKETS 

READ-CHECK 

0 

/NOREAD-CHECK 

WRITE_CHECK 

0 

/NOWRITE-CHECK 

FDL 

0 

/NOFDL 

EXCEPTION 

0 

/NOEXCEPTION 

PROLOG 

no default 

System or process default 


If you want to use the default null character for the PAD qualifier, you should 
specify 0 in the pad character longword. You can also specify the default null 
character by omitting the pad character longword. However, in this case, you 
must also take the default values for all subsequent qualifiers. To specify a 
pad character other than 0 , place the ASCII value of the character you want 
to use in the pad qualifier longword. 

If you specify /EXIT and the utility encounters an exception record, then 
CONVERT will return with a fatal exception status. 

If you specified an FDL file specification in the CONV$PASS_FILES routine, 
you must place a 2 in the FDL longword. If you have also specified an 
exceptions file specification in the CONV$PASS_FILES routine, you must 
place a 2 in the EXCEPTION longword. You may specify either, both, or 
neither of these files, but the values in the CONV$PASS_FILES call must 
match the values in the parameter list. If they do not, you will receive an 
error. 

If you specify the PROLOG longword, note that this overrides the KEY 
PROLOG attribute supplied by the FDL file. You must supply one of three 
values for the PROLOG longword if you use it. The three values are 0,2, 
and 3 . A 0 value means that you want to use the system or process prolog 
type. A 2 value means that you want to create a Prolog 1 or 2 file in all 
instances, even when circumstances would allow you to create a Prolog 3 file. 
A 3 value means that you want to create a Prolog 3 file and, if circumstances 
do not allow you to, you want the conversion to fail. 
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flags 

VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


Flags (or masks) that control how the fdl-file-spec argument is interpreted 
and how errors are signalled. The flags argument is the address of a 
longword containing the control flags (or a mask). If this argument is omitted 
or is specified as zero, no flags are set. If you specify a flag, it remains in 
effect until you explicitly reset it in a subsequent call to a Convert routine. 

The flags and their meanings are described below. 


Flag 

Function 

CONV$V_FDL —STRING 

Interprets the fdl-file-spec argument supplied in the 
call to CONV$PASS_FILES as an FDL specification in 
string form. By default, this argument is interpreted 
as a file name of an FDL file. 

FDL$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signalled. 


DESCRIPTION The following example shows how to invoke CONVERT with only the 

qualifiers /FAST_LOAD /SORT /WORK_FILES=6 /EXIT. You must set up 
an array of longwords with the values shown below: 


A: 


12 Specifies that 12 longwords follow 
0 Specifies the /NOCREATE option 
0 Specifies the /NOSHARE option 
1 Specifies the /FASTLOAD option 
0 Specifies no /MERGE option 
0 Specifies the /NOAPPEND option 
1 Specifies the /SORT option 
6 Specifies the /WORKFILES=6 option 
0 Specifies the /KEY=0 option 
0 Specifies the /NOPAD option 
0 Specifies the null pad character 
0 Specifies the /NOTRUNCATE option 
1 Specifies the /EXIT option 
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CONDITION 

VALUES 

RETURNED 



SS$_NORMAL 

CONV$_BADBLK 

CONV$_CONFQUAL 

CONV$_INSVIRMEM 

CONV$_NARG 

CONV$_OPENEXC 

CONV$_ORDER 


Normal successful completion. 

Invalid option block. 

Conflicting qualifiers. 

Insufficient virtual memory. 

Wrong number of arguments. 

Error opening exception file file-spec. 
Routine called out of order. 
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CONVSRECLAIM 


CONV$RECLAIM—CONVERT/Reclaim 



Invokes the functions of the Convert/Reclaim Utility. 

FORMAT 

CONV$RECLAIM input-file-spec[,statistics—blk] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

input-file-spec 

VMS Usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor-fixed length string descriptor 

The name of the Prolog 3 indexed file to be reclaimed. The input-file-spec 
argument is the address of a string descriptor pointing to the name of the 
Prolog 3 indexed file. 

statistics—blk 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Bucket reclamation statistics. The statistics_blk argument is the address 
of a variable-length array of longwords to receive statistics on the bucket 
reclamation. The format of the statistics array is shown below: 

A: Number of statistics 

Data buckets scanned 

Data buckets reclaimed 

Index buckets reclaimed 

Total buckets reclaimed 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

CONV$_BADLOGIC Internal logic error detected. 

CONV$_INSVIRMEM Insufficient virtual memory. 

CONV$_INVBKT Invalid bucket at VBN n. 
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CONV$RECLAIM 


CONV$_NOTIDX 

CONV$_OPENIN 

CONV$_PLV 

CONV$_PROERR 

CON V$_PROL _WRT 

CONV$_READERR 

CONV$_NOWILD 

CONV$_WRITEERR 


File is not an index file. 

Error opening file-spec as input. 
Unsupported prolog version. 
Error reading prolog. 

Prolog write error. 

Error reading file-spec. 

No wildcard permitted. 

Error writing output file. 
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5.1 Introduction to DCX Routines 

The set of routines described in this section comprises the VAX/VMS Data 
Compression/Expansion (DCX) facility. There is no DCL-level interface to 
this facility, nor is there a DCX Utility. 

Using the DCX routines described in this section, a user can decrease the size 
of any kind of data: text, binary data, images, and so on. 

Compressed data uses less space, but there is a trade-off in terms of access 
time to the data. Compressed data must first be expanded back to its original 
state before it is usable. Thus, infrequently accessed data makes a good 
candidate for data compression. 

The DCX facility provides routines that analyze and compress data records 
and that expand the compressed records to their original state. In this process, 
no information whatsoever is lost. A data record that has been compressed 
and then expanded is in the same state it was before it was compressed. 

Most collections of data can be reduced in size by DCX. However, there is 
no guarantee that the size of an individual data record will always be smaller 
after compression; in fact, some may grow larger. 

The DCX facility allows for the independent analysis, compression, and 
expansion of more than one stream of data records at the same time. This 
capability is provided by means of a "context variable", which is an argument 
in each DCX routine. Most applications will have no need for this capability; 
for these applications, there will be a single context variable. 

The procedure for using the DCX routines to perform data compression and 
expansion consists of three major steps; the list under each of the following 
steps shows which DCX routines are used to perform the step: 

1 Analyzing some or all of the data records in the data file to produce a 
mapping function (or map) 

DCX$ AN ALYZE _INIT 
DCX$ AN ALYZE _D ATA 
DCX$M AKE _MAP 
DCX$ AN ALYZE _DONE 

2 Compressing the data records in the file on the basis of the mapping 
function 

DCX$COMPRESS_INIT 

DCX$COMPRESS_DATA 

DCX$COMPRESS_DONE 
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3 Expanding the compressed data records on the basis of the mapping 


function 


DCX$EXPAND_INIT 

DCX$EXPAND_DATA 

DCX$EXPAND_DONE 

Some of the DCX routines make calls to various Run-Time Library (RTL) 
routines, for example, to LIB$GET_VM. If any of these RTL routines should 
fail, a return status code indicating the cause of the failure is returned. In 
such a case, the user must refer to the documentation of the appropriate RTL 
routine to determine the cause of the failure. The status codes documented in 
this section are primarily DCX status codes. 



5.2 Example of Using the DCX Routines 


The following example shows how to use the DCX routines in a VAX 
FORTRAN program. 
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Example of Using the DCX Routines 


Example DCX-1 Example of Compressing a File in a VAX 

FORTRAN Program 


PROGRAM COMPRESS.FILES 
! COMPRESSION OF FILES 

! status variable 
INTEGER STATUS. 

2 IOSTAT, 

2 IO.OK, 

2 STATUS.OK 

PARAMETER (I0_0K = 0) 

PARAMETER (STATUS.OK = 1) 

INCLUDE '($F0RDEF)' 

EXTERNAL DCX$_AGAIN 

! context variable 
INTEGER CONTEXT 

! compression/expansion function 
INTEGER MAP, 

2 MAP.LEN 

! normal file name, length, and logical unit number 
CHARACTER*256 NORM.NAME 
INTEGER*2 NORM.LEN 
INTEGER NORM.LUN 

! compressed file name, length, and logical unit number 
CHARACTER*256 COMP.NAME 
INTEGER*2 COMP.LEN 
INTEGER COMP.LUN 

! Logical end-of-file 
LOGICAL EOF 

! record buffers; 32767 is maximum record size 
CHARACTER*32767 RECORD, 

2 REC0RD2 

INTEGER RECORD.LEN, 

2 REC0RD2.LEN 

! user routine 
INTEGER GET.MAP, 

2 WRITE.MAP 


(Continued on next page) 
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Example DCX-1 (Cont.) Example of Compressing a File in a 

VAX FORTRAN Program 


! Library procedures 
INTEGER DCX$ANALYZE_INIT, 

2 DCX$ANALYZE_DONE, 

2 DCX$COMPRESS_INIT, 

2 DCX$COMPRESS_DATA, 

2 DCX$COMPRESS_DONE, 

2 LIB$GET_INPUT, 

2 LIB$GET_LUN, 

2 LIB$FREE_VM 

! get name of file to be compressed and open it 
STATUS = LIB$GET_INPUT (NORM,NAME, 

2 'File to compress: 

2 NORM.LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (y.VAL(STATUS)) 
STATUS = LIB$GET_LUN (NORM.LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 
OPEN (UNIT = NORM.LUN, 

2 FILE = N0RM_NAME(1:N0RM_LEN), 

2 CARRIAGECONTROL = 'NONE', 

2 STATUS = 'OLD') 

1 ************ 

! ANALYZE DATA 

j ************ 

! initialize work area 

STATUS = DCX$ANALYZE_INIT (CONTEXT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 
! get compression/expansion function (map) 

STATUS = GET.MAP (NORM.LUN. 

2 CONTEXT, 

2 MAP, 

2 MAP.LEN) 

DO WHILE (STATUS .EQ. 7.L0C(DCX$_AGAIN)) 

! go back to beginning of file 
REWIND (UNIT = NORM.LUN) 

! try map again 

STATUS = GET.MAP (NORM.LUN, 

2 CONTEXT, 

2 MAP, 

2 MAP.LEN) 

END DO 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 

! clean up work area 

STATUS = DCX$ANALYZE_DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 


(Continued on next page) 
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Example of Using the DCX Routines 


Example DCX—1 (Cont.) Example of Compressing a File in a 

VAX FORTRAN Program 


! ************* 

! COMPRESS DATA 

i ************* 

! go back to beginning of file to be compressed 
REWIND (UNIT = NORM.LUN) 

! open file to hold compressed records 
STATUS = LIB$GET_LUN (COMP.LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 
STATUS = LIB$GET_INPUT (COMP.NAME, 

2 'File for compressed records: 

2 COMP.LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 

OPEN (UNIT = COMP.LUN. 

2 FILE = C0MP_NAME(1:COMP.LEN), 

2 STATUS = 'NEW', 

2 FORM = 'UNFORMATTED') 

! initialize work area 

STATUS = DCX$COMPRESS_INIT (CONTEXT. 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 

! write compression/expansion function to new file 
CALL WRITE.MAP (COMP.LUN. 

2 7.VAL(MAP), 

2 MAP.LEN) 

! read record from file to be compressed 
EOF = .FALSE. 

READ (UNIT = NORM.LUN, 

2 FMT = '(Q,A)', 

2 IOSTAT = IOSTAT) RECORD.LEN, 

2 RECORD(1:RECORD.LEN) 

IF (IOSTAT .NE. IO.OK) THEN 
CALL ERRSNS (,...STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (7.VAL (STATUS) ) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS.OK 
END IF 
END IF 


(Continued on next page) 
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Example DCX-1 (Cont.) Example of Compressing a File in a 

VAX FORTRAN Program 


DO WHILE (.NOT. EOF) 

! compress the record 

STATUS = DCX$COMPRESS_DATA (CONTEXT, 

2 RECORD(1:RECORD.LEN), 

2 REC0RD2, 

2 REC0RD2.LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (*/.VAL(STATUS)) 

! write compressed record to new file 

WRITE (UNIT = COMP.LUN) REC0RD2.LEN 

WRITE (UNIT = COMP.LUN) REC0RD2 (1:REC0RD2.LEN) 

! read from file to be compresses 
READ (UNIT = NORM.LUN, 

2 FMT = '(Q,A)', 

2 IOSTAT = IOSTAT) RECORD.LEN, 

2 RECORD (1:RECORD.LEN) 

IF (IOSTAT .NE. IO.OK) THEN 
CALL ERRSNS (,.,.STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (y.VAL(STATUS)) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS.OK 
END IF 
END IF 
END DO 

! close files and clean up work area 
CLOSE (NORM.LUN) 

CLOSE (COMP.LUN) 

STATUS = LIB$FREE_VM (MAP.LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL ('/.VAL(STATUS)) 
STATUS = DCX$COMPRESS_DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL ( % VAL(STATUS)) 

END 


INTEGER FUNCTION GET.MAP (LUN, 

2 CONTEXT, 

2 MAP. 

2 MAP.LEN) 


! passed 
! passed 
! returned 
! returned 


! Analyzes records in file opened on logical 
! unit LUN and then attempts to create a 
! compression/expansion function using 
! DCX$MAKE_MAP. 


(Continued on next page) 
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Example DCX-1 (Cont.) Example of Compressing a File in a 

VAX FORTRAN Program 


! dummy arguments 
! context variable 
INTEGER CONTEXT 
! logical unit number 
INTEGER LUN 

! compression/expan8ion function 
INTEGER MAP, 

2 MAP.LEN 

! status variable 
INTEGER STATUS. 

2 IOSTAT, 

2 IO.OK, 

2 STATUS.OK 

PARAMETER (IO.OK = 0) 

PARAMETER (STATUS.OK = 1) 

INCLUDE '($F0RDEF)' 

! Logical end-of-file 
LOGICAL EOF 

! record buffer; 32767 is the maximum record size 
CHARACTER*32767 RECORD 
INTEGER RECORD.LEN 

! library procedures 
INTEGER DCX$ANALYZE_DATA, 

2 DCX$MAKE_MAP 

! analyze records 
EOF = .FALSE. 

READ (UNIT = LUN, 

2 FMT = '(Q,A)', 

2 IOSTAT = IOSTAT) RECORD.LEN,RECORD 
IF (IOSTAT .NE. IO.OK) THEN 
CALL ERRSNS (,,,.STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (7.VAL(STATUS) ) 

ELSE 

EOF * .TRUE. 

STATUS = STATUS.OK 
END IF 
END IF 


(Continued on next page) 
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Example DCX-1 (Cont.) Example of Compressing a File in a 

VAX FORTRAN Program 


DO WHILE (.NOT. EOF) 

STATUS = DCX$ANALYZE_DATA (CONTEXT, 

2 RECORD(1:RECORD_LEN)) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
READ (UNIT = LUN, 

2 FMT = '(Q,A)', 

2 IOSTAT = IOSTAT) RECORD.LEN,RECORD 

IF (IOSTAT .NE. IO.OK) THEN 
CALL ERRSNS (,,,,STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL ( # /.VAL(STATUS) ) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS.OK 
END IF 
END IF 
END DO 

STATUS 
2 
2 

GET.MAP 
END 

SUBROUTINE WRITE.MAP (LUN, ! passed 

2 MAP, ! passed 

2 MAP.LEN) ! passed 

IMPLICIT INTEGER(A-Z) 

! write compression/expansion function 
! to file of compressed data 
! dummy arguments 

INTEGER LUN, ! logical unit of file 

2 MAP_LEN ! length of function 

BYTE MAP (MAP.LEN) ! compression/expansion function 

! write map length 
WRITE (UNIT = LUN) MAP.LEN 
! write map 

WRITE (UNIT = LUN) MAP 
END 


= DCX$MAKE_MAP (CONTEXT, 
MAP, 

MAP.LEN) 

= STATUS 
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Example DCX-2 Example of Expanding a Compressed File in a 
VAX FORTRAN Program 


PROGRAM EXPAND.FILES 
IMPLICIT INTEGER(A-Z) 

! EXPANSION OF COMPRESSED FILES 
! file names, lengths, and logical unit numbers 
CHARACTER*256 OLD.FILE, 

2 NEW.FILE 

INTEGER*2 OLD.LEN, 

2 NEW.LEN 

INTEGER OLD.LUN, 

2 NEW.LUN 

! length of compression/expansion function 
INTEGER MAP, 

2 MAP.LEN 

! user routine 
EXTERNAL EXPAND.DATA 
! library procedures 
INTEGER LIB$GET_LUN, 

2 LIB$GET_INPUT, 

2 LIB$GET_VM, 

2 LIB$FREE_VM 

! open file to expand 
STATUS = LIB$GET_LUN (OLD.LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 

STATUS = LIB$GET_INPUT (OLD.FILE, 

2 'File to expand: 

2 OLD.LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 

OPEN (UNIT = OLD.LUN, 

2 STATUS = 'OLD', 

2 FILE = 0LD_FILE(1:0LD_LEN), 

2 FORM = 'UNFORMATTED') 

! open file to hold expanded data 
STATUS = LIB$GET_LUN (NEW.LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 

STATUS = LIB$GET_INPUT (NEW.FILE, 

2 'File to hold expanded data: ' 

2 NEW.LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 

OPEN (UNIT = NEW.LUN, 

2 STATUS = 'NEW', 

2 CARRIAGECONTROL = 'LIST', 

2 FILE = NEW_FILE(1:NEW.LEN)) 


(Continued on next page) 
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Example DCX-2 (Cont.) Example of Expanding a Compressed 

File in a VAX FORTRAN Program 


! expand file 

! get length of compression/expansion function 
READ (UNIT = OLD.LUN) MAP.LEN 
STATUS = LIB$GET_VM (MAP.LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 

! expand records 

CALL EXPAND.DATA (7.VAL(MAP) , 

2 MAP_LEN, ! length of function 

2 OLD.LUN, ! compressed data file 

2 NEW.LUN) ! expanded data file 

! delete virtual memory used for function 
STATUS = LIB$FREE_VM (MAP.LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS)) 

END 


SUBROUTINE EXPAND.DATA (MAP, ! passed 

2 MAP.LEN, ! passed 

2 OLD.LUN, ! passed 

2 NEW.LUN) ! passed 

! expand data program 

• dummy arguments 

INTEGER MAP.LEN, ! length of expansion function 
2 OLD.LUN, ! logical unit of compressed file 

2 NEW.LUN ! logical unit of expanded file 

BYTE MAP(MAP.LEN) ! array containing the function 

! status variables 
INTEGER STATUS. 

2 IOSTAT, 

2 IO.OK, 

2 STATUS.OK 

PARAMETER (IO.OK = 0) 

PARAMETER (STATUS.OK = 1) 

INCLUDE '($F0RDEF) 1 


! context variable 
INTEGER CONTEXT 


! logical end.of.file 
LOGICAL EOF 
! record buffers 
CHARACTER*32767 RECORD, 
2 REC0RD2 

INTEGER RECORD.LEN, 

2 REC0RD2.LEN 


(Continued on next page) 
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Example DCX-2 (Cont.) Example of Expanding a Compressed 

File in a VAX FORTRAN Program 


! library procedures 
INTEGER DCX$EXPAND_INIT, 

2 DCXlEXPAND.DATA, 

2 DCX$EXPAND_DONE 

! read data compression/expansion function 

READ (UNIT = OLD.LUN) MAP 

! initialize work area 

STATUS = DCX$EXPAND_INIT (CONTEXT, 

2 7,L0C(MAP(1) ) ) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

! expand records 
EOF = .FALSE. 

! read length of compressed record 
READ (UNIT * OLD.LUN. 

2 IOSTAT * IOSTAT) RECORD.LEN 
IF (IOSTAT .NE. IO.OK) THEN 
CALL ERRSNS (,,,,STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (7.VAL(STATUS) ) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS.OK 
END IF 
END IF 

DO WHILE (.NOT. EOF) 

! read compressed record 

READ (UNIT = OLD.LUN) RECORD (1:RECORD.LEN) 

! expand record 

STATUS = DCX$EXPAND_DATA (CONTEXT, 

2 RECORD(1:RECORD.LEN), 

2 REC0RD2, 

2 REC0RD2.LEN) 

IF (.NOT. STATUS) CALL LIBlSIGNAL OiVAL(STATUS)) 
! write expanded record to new file 
WRITE (UNIT = NEW.LUN, 

2 FMT = '(A)') REC0RD2(1:REC0RD2.LEN) 

! read length of compressed record 
READ (UNIT = OLD.LUN, 

2 IOSTAT = IOSTAT) RECORD.LEN 

IF (IOSTAT .NE. IO.OK) THEN 
CALL ERRSNS (.,,,STATUS) 

IF (STATUS .NE. FORl.ENDDURREA) THEN 
CALL LIBlSIGNAL (7.VAL(STATUS)) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS.OK 
END IF 
END IF 
END DO 

! clean up work area 

STATUS = DCXIEXPAND.DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIBlSIGNAL (7.VAL(STATUS)) 
END 


5.3 DCX Routines 


The following pages describe the individual DCX routines in routine template 
format. 
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DCX$ANALYZE_DATA 


DCX$AN ALYZE —DATA 

Performs statistical analysis on a data record. The results of analysis 
are accumulated internally in the context area and will be used by 
the DCX$MAKE_MAP routine to compute the mapping function. 


FORMAT DCX$ANALYZE_DATA context,record 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 


ARGUMENTS 


context 

VMS Usage: 
type: 
access: 
mechanism: 


context 

longword (unsigned) 
read only 
by reference 


Value identifying the data stream which DCX$ AN ALYZE—DATA analyzes. 
The context argument is the address of a longword containing this context 
value. DCX$ANALYZE—INIT initializes this context; you should not modify 
its value. Multiple context arguments may be defined to identify multiple 
data streams which are processed simultaneously. 


record 

VMS Usage: 
type: 
access: 
mechanism: 


char—string 
character string 
read only 
by descriptor 


The record which is analyzed. DCX$ANALYZE_DATA reads the record 
argument, which is the address of a descriptor for the record string. 
Maximum length of the record string is 65535 characters. 


DESCRIPTION The DCX$ANALYZE_DATA routine performs statistical analysis on a single 

data record. This routine is called once for each data record to be analyzed. 

During analysis, the data compression facility gathers information that 
DCX$MAKE—MAP will use to create the compression/expansion function 
for the file. After the data records have been analyzed, the user calls the 
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status 
code from DCX$MAKE_MAP, the user must again analyze the same data 
records (in the same order) using DCX$ANALYZE— DATA and then call 
DCX$MAKE_MAP again. On the second iteration, DCX$MAKE_MAP 
returns the DCX$_NORMAL status code, and the data analysis is complete. 
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CONDITION 

VALUES 

RETURNED 


DCX$_INVCTX Error; the context variable is invalid, or the context 

area is invalid or corrupted. This may be caused by 
a failure to call the appropriate routine to initialize 
the context variable or by an application program 
error. 

DCX$_NORMAL Successful completion. 

Any condition values returned by LIB$ANALYZE_SDESC_R2. 
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DCX$ANALYZE_DONE 


DCX$AN ALYZE -DONE 



Deletes the context area and sets to zero the context variable, thus 
undoing the work of the DCX$ANALYZE_INIT routine. The user 
calls DCX$ANALYZE_DONE after data records have been analyzed 
and the DCX$MAKE_MAP routine has created the map. 

FORMAT 

DCX$ANALYZE_DONE context 

RETURNS 

VMS Usage: cond—value 
type: long word 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

context 

VMS Usage: context 
type: longword 

access: write only 

mechanism: by reference 

Value identifying the data stream which DCX$ AN ALYZE _DONE deletes. 

The context argument is the address of a longword containing this context 
value. DCX$ AN ALYZE _INIT initializes this context; you should not modify 
its value. Multiple context arguments may be defined to identify multiple 
data streams which are processed simultaneously. 


DESCRIPTION The DCX$ANALYZE—DONE routine deletes the context area and 

sets to zero the context variable, thus undoing the work of the 



DCX$ AN ALYZE _INIT routine. The user calls DCX$ AN ALYZE-DONE after 
data records have been analyzed and the DCX$MAKE_MAP routine has 
created the mapping function. 

CONDITION 

VALUES 

RETURNED 

DCX$_INVCTX Error; the context variable is invalid, or the context 

area is invalid or corrupted. This may be caused by 
a failure to call the appropriate routine to initialize 
the context variable or by an application program 
error. 

DCX$_NORMAL Successful completion. 

Any condition values returned by LIB$FREE_VM. 
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DCX$ANALYZE_INIT 


DCX$AN ALYZE _l N IT 



Initializes the context area for a statistical analysis of the data 
records to be compressed. 

FORMAT 

DCX$ANALYZE_INIT context [,item-code 

Jtem-value] 

The second and third arguments are both optional but, if specified, must be 
specified together. Further, this pair of arguments may be repeated, with 
different values, in the same call. 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

context 

VMS Usage: context 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Value identifying the data stream which DCX$ AN ALYZE _INIT initializes. 
The context argument is the address of a longword containing this context 
value. DCX$ AN ALYZE _INIT writes this context into the context argument; 
you should not modify its value. Multiple context arguments may be defined 
to identify multiple data streams which are processed simultaneously. 

item-code 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

A symbolic code specifying information that the user wishes 

DCX$ AN ALYZE—INIT to use in its analysis of data records and in its 
computation of the mapping function. DCX$ AN ALYZE _INIT reads this 
item-code argument, which is the address of the longword contained in the 

item-code. 

For each item-code argument specified in the call, the user must also 
specify a corresponding item-value argument. The item-value contains 
the interpretation of the item-code argument. 

The following five symbolic names are the five legal values of the item-code 
argument: 

DCX$C_BOUNDED 
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DCX$ANALYZE_INIT 


DCX$C_EST_BYTES 
DCX$C_EST_RECORDS 
DCX$C_LIST 
DCX$C_ONE —PASS 


item-value 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Value of the corresponding item-code argument. DCX$ANALYZE_JNIT 
reads the item-value argument, which is the address of a longword 
containing item-value. 

Item-code and item-value always occur as a pair, and together they specify 
one piece of "advice" for the DCX routines to use in computing the map 
function. Note that, unless stated otherwise in the list of item codes and item 
values, no piece of "advice" is binding on DCX; that is, DCX is free to follow 
or not follow the "advice." 


The following list shows, for each item-code argument, the possible values of 
the corresponding item-value argument. 


Item-code Corresponding item-value 

DCX$C_BOUNDED A Boolean variable. If bit <0> is true (equals 1 ), 

the user is stating his intention to submit for analysis 
all data records that will be compressed; doing so will 
often enable DCX to compute a better compression 
algorithm. If bit <0> is false (equals 0 ) or if the 
DCX$C_BOUNDED item code is not specified, DCX 
computes a compression algorithm without regard for 
whether all records to be compressed will also be 
submitted for analysis. 

DCX$C_EST_BYTES A longword value containing the user's estimate of 

the total number of data bytes that will be submitted 
for compression; this estimate is useful in those 
cases where fewer than the total number of bytes are 
presented for analysis. If the DCX$C_EST_BYTES 
item code is not specified, DCX assumes that the 
number of bytes presented for analysis is the number 
of bytes that will be submitted for compression. Note 
that the user may specify one of or both 
DCX$C_EST_RECORDS and DCX$C_EST_BYTES. 

DCX$C_EST_RECORDS A longword value containing the user's estimate 

of the total number of data records that will be 
submitted for compression; this estimate is useful in 
those cases where fewer than the total number of 
records are presented for analysis. If the 
DCX$C_EST_RECORDS item code is not specified, 
DCX assumes that the number of records presented 
for analysis is the number of records that will be 
submitted for compression. 
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DCX$ANALYZE_INIT 


Item-code Corresponding item-value 


DCX$C_LIST Address of an array of 2*n+1 longwords. The first 

longword in the array contains the value 2*n+1. The 
remaining longwords are paired; there are n pairs. 

The first member of the pair is an item code, and 
the second member of the pair is the address of its 
corresponding item value. The DCX$C_LIST item 
code allows a user to construct an array of item-code 
and item-value pairs and then to pass the entire array 
to DCX$ANALYZE_INIT. This is useful when the 
user's language has difficulty interpreting variable- 
length argument lists. Note that the DCX$C_LIST 
item code may be specified, in a single call, alone 
or together with any of the other item-code and 
item-value pairs. 

DCX$C_ONE_PASS A Boolean variable. If bit <0> is true (equals 1), 

the user makes a binding request that DCX make only 
one pass over the data to be analyzed. If bit <0> 
is false (equals 0) or if the DCX$C_ONE_PASS item 
code is not specified, DCX may make multiple passes 
over the data, as required. Typically, DCX makes one 
pass. 


DESCRIPTION The DCX$ANALYZE_JNIT routine initializes the context area for a statistical 

analysis of the data records to be compressed. The first (and typically the 
only) argument passed to DCX$ANALYZE_INIT is an integer variable to 
contain the context value. The data compression facility assigns a value to the 
context variable and associates the value with the created work area. Each 
time you want a record analyzed in that area, specify the associated context 
variable. You can analyze two or more files at once by creating a different 
work area for each file, giving each area a different context variable, and 
analyzing the records of each file in the appropriate work area. 


CONDITION DCX$_INVITEM 

VALUES 

RETURNED 

DCX$_NORMAL 


Error; invalid item code; the number of arguments 
specified in the call was incorrect (this number 
should be odd), or an unknown item code was 
specified. 

Successful completion. 


Any condition values returned by LIB$GET_VM. 
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DCX$COMPRESS_DATA 


DCX$COMPRESS_DATA 



Compresses a data record. The user calls this routine for each data 
record to be compressed. 

FORMAT 

DCX$COMPRESS_DATA context ,'m-rec ,out-rec 

[,out-length] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

context 

VMS Usage: context 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Value identifying the data stream which DCX$COMPRESS_DATA 
compresses. The context argument is the address of a longword containing 
this context. DCX$COMPRESS_INIT initializes the value; you should not 
modify it. Multiple context arguments may be defined to identify multiple 
data streams which are processed simultaneously. 

in-rec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The data record to be compressed. The in-rec argument is the address of the 
descriptor of the data record string. 

out-rec 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

The data record that has been compressed. The out-rec argument is the 
address of the descriptor of the compressed record which 
LIB$COMPRESS_DATA returns. 
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DCX$CO M PR ESS-DATA 


out-length 


VMS Usage: 
type: 
access: 
mechanism: 


word_signed 
word integer (signed) 
write only 
by reference 


The length (in bytes) of the compressed data record. The out-length 
argument is the address of a word into which LIB$COMPRESS_DATA 
returns the length of the compressed data record. 


DESCRIPTION The DCX$COMPRESS_DATA routine compresses a data record. The 

user calls this routine for each data record to be compressed. As you 
compress each record, write the compressed record to the file containing 
the compression/expansion map. For each record, write the length of the 
record and substring string containing the record to the same file. See the 
COMPRESS DATA section in the example. 


CONDITION DCX$_INVCTX 

VALUES 

RETURNED 

DCX$_IN VD AT A 


DCX$_INVMAP 

DCX$_NORMAL 

DCX$_TRUNC 


Error; the context variable is invalid, or the context 
area is invalid or corrupted. This may be caused by 
a failure to call the appropriate routine to initialize 
the context variable or by an application program 
error. 

Error; the user has specified the item value 
DCX$C_BOUNDED in the DCX$ANALYZE_INIT 
routine and has attempted to compress a data 
record (using DCX$COMPRESS_DATA) that was 
not presented for analysis (using DCX$ANALYZE_ 
DATA). Specifying the DCX$C_BOUNDED item 
value means that you must analyze all data records 
that are to be compressed. 

Error; invalid map; the map argument was not 
specified correctly or the context area is invalid. 

Successful completion. 

Error; the compressed data record has been 
truncated because the out-rec descriptor did not 
specify enough memory to accommodate the 
record. 


Any condition values returned by LIB$ANALYZE_SDESC_R2 and 
LIB$SCOPY_R_DX. 
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DCX$COMPRESS_DONE 


DCX$COMPRESS_DONE 



Deletes the context area and sets to zero the context variable, thus 
undoing the work of the DCX$COMPRESS_INIT routine. The user 
calls DCX$COMPRESS_DONE when all data records have been 
compressed (using DCX$COMPRESS_DATA). 

FORMAT 

DCX$COMPRESS_DONE context 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

context 

VMS Usage: context 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Value identifying the data stream which DCX$COMPRESS_DONE deletes. 
The context argument is the address of a longword containing this context 
value. DCX$COMPRESS_JNIT writes the context into context; you should 
not modify its value. Multiple context arguments may be defined to identify 
multiple data streams which are processed simultaneously. 

DESCRIPTION 

The DCX$COMPRESS_DONE routine deletes the context area and sets to 
zero the context variable, thus undoing the work of the DCX$COMPRESS_ 
INIT routine. The user calls DCX$COMPRESS__DONE when all data records 
have been compressed (using DCX$COMPRESS_DATA). After calling 
DCX$COMPRESS_DONE, call LIB$FREE_VM to free the virtual memory 
that DCX$MAKE_MAP used for the compression/expansion function. 

CONDITION 

VALUES 

RETURNED 

DCX$_INVCTX Error; the context variable is invalid or the context 

area is invalid or corrupted. This may be caused by 
a failure to call the appropriate routine to initialize 
the context variable or by an application program 
error. 

DCX$_NORMAL Successful completion. 

Any condition values returned by LIB$FREE_VM. 
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DCX$COM PR ESS_I N IT 


DCX$COMPRESS_INIT 



Initializes the context area for the compression of data records. 

FORMAT 

DCX$COMPRESS_INIT context,map 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

context 

VMS Usage: context 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Value identifying the data stream which DCX$COMPRESS_INIT initializes. 
The context argument is the address of a longword containing this context 
value. You should not modify the context value after DCX$COMPRESS_INIT 
initializes it. Multiple context arguments may be defined to identify multiple 
data streams which are processed simultaneously. 

map 

VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The function created by DCX$MAKE_MAP. The map argument is the 
address of the compression/expansion function's virtual address. 

The map must remain at this address until data compression is completed 
and the context is deleted by means of a call to DCX$COMPRESS_DONE. 

DESCRIPTION 

The DCX$COMPRESS_INIT routine initializes the context area for the 
compression of data records. 

The user calls the DCX$COMPRESS_INIT routine after the call to 

DCX$ ANALYZE _DONE. 
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DCX$COMPRESS_INIT 


CONDITION 

VALUES 

RETURNED 


DCX$_INVMAP Error; invalid map; the map argument was not 

specified correctly, or the context area is invalid. 

DCX$_NORMAL Successful completion. 

Any condition values returned by LIB$GET_VM and LIB$FREE_VM. 
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DCX$ EXPAN D—DATA 


DCX$EXP AN D_D AT A 



Expands (or restores) a compressed data record to its original 
state. The user calls this routine for each data record that is to be 
expanded. 

FORMAT 

DCX$EXPAN D_DATA context , in-rec, out-rec 

[, out-length] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

context 

VMS Usage: context 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Value identifying the data stream which DCX$EXPAND_DATA expands. The 
context argument is the address of a longword containing this context value. 
DCX$EXPAND_INIT initializes this context; you should not modify its value. 
Multiple context arguments may be defined to identify multiple data streams 
which are processed simultaneously. 

in-rec 

VMS Usage: char__string 
type: character string 

access: read only 

mechanism: by descriptor 

The data record to be expanded. The in-rec argument is the address of the 
descriptor of the data record string. 

out-rec 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

The data record that has been expanded. The out-rec argument is the address 
of the descriptor of the expanded record which DCX$EXPAND_DATA 
returns. 
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DCX$EXPAND_DATA 


out-length 


VMS Usage: 
type: 
access: 
mechanism: 


word—signed 
word integer (signed) 
write only 
by reference 


The length (in bytes) of the expanded data record. The out-length argument 
is the address of a word into which DCX$EXPAND—DATA returns the length 
of the expanded data record. 


DESCRIPTION The DCX$EXPAND—DATA routine expands (or restores) a compressed data 

record to its original state. The user calls this routine for each data record that 
is to be expanded. 


CONDITION DCX$_INVCTX 

VALUES 

RETURNED 

DCX$_IN VDAT A 

DCX$_INVMAP 

DCX$_NORMAL 

DCX$_TRUNC 


Error; the context variable is invalid, or the context 
area is invalid or corrupted. This may be caused by 
a failure to call the appropriate routine to initialize 
the context variable or by an application program 
error. 

Error; a compressed data record is invalid 
(probably truncated) and therefore cannot be 
expanded. 

Error; invalid map; the map argument was not 
specified correctly or the context area is invalid. 

Successful completion. 

Warning; the expanded data record has been 
truncated because the out-rec descriptor did not 
specify enough memory to accommodate the 
record. 


Any condition values returned by LIB$ANALYZE— SDESC—R2 and 
LIB$SCOPY_R_DX. 
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DCX$EXPAND_DONE 


DCX$EXPAND_DONE 



Deletes the context area and sets to zero the context variable, thus 
undoing the work of the DCX$EXPAND_INIT routine. The user calls 
DCX$EXPAND_DONE when all data records have been expanded 
(using DCX$EXPAND_DATA). 

FORMAT 

DCX$EXPAND_DONE context 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

context 

VMS Usage: context 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Value identifying the data stream which DCX$EXPAND_DONE deletes. The 
context argument is the address of a longword containing this context value. 
DCX$EXPAND_INIT initializes this context value; you should not modify it. 
Multiple context arguments may be defined to identify multiple data streams 
which are processed simultaneously. 

DESCRIPTION 

The DCX$EXPAND_DONE routine deletes the context area and sets to zero 
the context variable, thus undoing the work of the DCX$EXPAND_INIT 
routine. The user calls DCX$EXPAND_DONE when all data records have 
been expanded (using DCX$EXPAND_DATA). 

CONDITION 

VALUES 

RETURNED 

DCX$_INVCTX Error; the context variable is invalid, or the context 

area is invalid or corrupted. This may be caused by 
a failure to call the appropriate routine to initialize 
the context variable or by an application program 
error. 

DCX$NORMAL Successful completion. 

Any condition values returned by LIB$FREE_VM. 
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DCX$EXPAND_INIT 


DCX$EXP AN D_l N IT 



Initializes the context area for the expansion of data records. 

FORMAT 

DCX$EXPAND_INIT context,map 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

context 

VMS Usage: context 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Value identifying the data stream which DCX$EXPAND_INIT initializes. 

The context argument is the address of a longword containing this context 
value. After DCX$EXPAND_INIT initializes this context value, you should 
not modify it. Multiple context arguments may be defined to identify multiple 
data streams which are processed simultaneously. 

map 

VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The function created by DCX$MAKE_MAP. The map argument is the 
address of the compression/expansion function's virtual address. 

The map must remain at this address until data compression is completed 
and the context is deleted by means of a call to DCX$EXPAND_DONE. 

DESCRIPTION 

The DCX$EXPAND_INIT routine initializes the context area for the 
expansion of data records. 

The user calls the DCX$EXPAND_INIT routine as the first step in the 
expansion (or restoration) of compressed data records to their original state. 

Before calling DCX$EXPAND_INIT, read the length of the compressed file 
from the compression/expansion function (the map). Invoke LIB$GET_VM to 
get the necessary amount of storage for the function. LIB$GET_VM returns 
the address of the first byte of the storage area. 
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DCX$EXPAND_INIT 


CONDITION 

VALUES 

RETURNED 


DCX$_INVMAP Error; invalid map. 

DCX$_NORMAL Successful completion. 

Any condition values returned by LIB$GET_VM. 
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DCX$MAKE_MAP 


DCX$M AKE -MAP 



Computes the mapping function, allocates a contiguous area of 
memory (using the LIB$GET_VM routine) in which it stores the 
compression/expansion function (or map), and returns the address 
and (optionally) the size of the map. 

FORMAT 

DCX$MAKE_MAP context ,map-addr[,map-size] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

context 

VMS Usage: context 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Value identifying the data stream which DCX$MAKE_MAP maps. The 
context argument is the address of a longword containing this context value. 
DCX$ANALYZE_INIT initializes this context value; you should not modify it. 
Multiple context arguments may be defined to identify multiple data streams 
which are processed simultaneously. 

map-addr 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Starting address of the compression/expansion function (or map). The 
map-addr is the address of a longword into which DCX$MAKE_MAP stores 
the virtual address of the compression/expansion function. 

map-size 

VMS Usage: longword_signed 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

The length of the compression/expansion function. The map-size is the 
address of the longword into which DCX$MAKE_MAP writes the length of 
the compression/expansion function. This is an optional argument. 
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DCX$MAKE_MAP 


DESCRIPTION The DCX$MAKE_MAP routine uses the statistical information gathered by 
DCX$ANALYZE_DATA to compute the compression/expansion function. 
This map is, in essence, the algorithm used to shorten (or compress) the 
original data records as well as to expand the compressed records to their 
original form. 

The map must be available in memory when any data compression or 
expansion takes place; the address of the map is passed as an argument to the 
DCX$COMPRESS_INIT and DCX$EXPAND_INIT routines, which initialize 
the data compression and expansion procedures, respectively. 

The map is stored with the compressed data records, since the compressed 
data records are indecipherable without the map. When compressed data 
records have been expanded to their original state and further compression is 
not desired, the user should delete the map using the LIB$FREE_VM routine. 

DCX requires that the user submit data records for analysis and then call the 
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code, 
the user must again submit data records for analysis (in the same order) and 
call DCX$MAKE_MAP again; on the second iteration, DCX$MAKE_MAP 
returns the DCX$_NORMAL status code. 


CONDITION DCXS—AGAIN 

VALUES 

RETURNED 


DCX$_INVCTX 


DCX$_NORMAL 


Informational; the map has not been created 
and the map-addr and map-size arguments 
have not been written because further analysis 
is required. The data records must be analyzed 
(using DCX$ANALYZE_DATA) again and 
DCX$MAKE_MAP must be called again before 
DCX$MAKE_MAP will create the map and return 
the DCX$_NORMAL status code. 

Error; the context variable is invalid, or the context 
area is invalid or corrupted. This may be caused by 
a failure to call the appropriate routine to initialize 
the context variable or by an application program 
error. 

Successful completion. 


Any condition values returned by LIB$GET_VM and LIB$FREE_VM. 
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6 EDT Routines 


6.1 




Introduction to EDT Routines 

EDT can be called on VAX/VMS operating systems by programs. Calling 
programs can be written in any VAX language that generates calls using the 
VAX Procedure Calling and Condition Handling Standard. 

You can set up your call to EDT so that the program handles all the editing 
work, or you can make EDT run interactively so that a user at the terminal 
can edit a file while the program is running. 

This section on callable EDT assumes that you know how to call an external 
facility from the language you are using. Callable EDT is a shareable image, 
which means that you save physical memory and disk space by having all 
processes access a single copy. 

You must include a statement in your program accessing the EDT entry 
point. This reference statement is similar to a library procedure reference 
statement. The EDT entry point is referenced as: EDT$EDIT. You can pass 
arguments to EDT$EDIT. For example, you can pass EDT$FILEIO or your 
own routine. When you refer to the routines you pass, call them fileio, 
workio, and xlate. Therefore, fileio can be either a routine provided by EDT 
(named EDT$FILEIO) or a routine that you write. 



Example of Using EDT Routines 

The following VAX BASIC program calls EDT. All three routines (FILEIO, 
WORKIO, and XLATE) are called. Note the reference to the entry point 
EDT$EDIT in line number 500. 
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Example of Using EDT Routines 


Example EDT-1 Using the EDT Routines in a VAX BASIC 
Program 


100 EXTERNAL INTEGER EDT$FILEIO O 
200 EXTERNAL INTEGER EDT$W0RKI0 
250 EXTERNAL INTEGER AXLATE 
300 EXTERNAL INTEGER FUNCTION EDT$EDIT 
400 DECLARE INTEGER RESULT 

450 DIM INTEGER PASSFILE(1%) © 

460 DIM INTEGER PASSW0RK(1%) 

465 DIM INTEGER PASSXLATE(iy.) 

470 PASSFILE(OX) = L0C(EDT$FILEI0) 

480 PASSW0RK(0%) = L0C(EDT$W0RKI0) 

485 PASSXLATE(0%) = LOC(AXLATE) 

500 RESULT = EDT$EDIT('FILE.BAS'. " .'EDTINI 1 ,•',0%. © 

PASSFILE(0%)BY REF. PASSW0RK(0y.) BY REF. © 

PASSXLATE(0%) BY REF) © 

600 IF (RESULT AND 1%) * 0% 

THEN 

PRINT "SOMETHING WRONG" 

CALL LIBtSTOP(RESULT BY VALUE) 

900 PRINT "EVERYTHING O.K." 

1000 END 

© The external entry points EDT$FILEIO, EDT$WORKIO, and AXLATE are 
defined so that they can be passed to callable EDT. 

© Arrays are used to construct the two-longword structure needed for data 
type BPV. 

© Here is the call to EDT. The input file is FILE.BAS, the output and journal 
files are defaulted, and the command file is EDTINI. A 0 is passed for the 
options word to get the default EDT options. 

© The array PASSFILE points to the entry point for all file I/O, which 
is set up above to be the EDT supplied routine with the entry point 
EDT$FILEIO. Similarly, the array PASSWORK points to the entry point 
for all work I/O, which is the EDT supplied routine with the entry point 
EDT$WORKIO. 

© PASSXLATE points to the entry point that will be used by EDT for all 
XLATE processing. PASSXLATE points to a user-supplied routine with the 
entry point AXLATE. 


6.3 EDT Routines 


The following pages describe the individual EDT routines in routine template 
format. 
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EDTSEDIT 


EDT$EDIT 

—Edit a File 


Invokes the EDT editor. 

FORMAT 

EDT$EDIT in—file [,out—file][,com—file][,jou—file] 

[, options] [, fileio] [, workio] [,xlate] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


The Condition Values Returned can indicate: ( 1 ) a successful completion, ( 2 ) 
a termination caused by an internal EDT error, or ( 3 ) a termination caused 
by problems in one of the procedures, fileio or workio. 


ARGUMENTS 


in—file 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 
read only 
by descriptor 


File specification of the input file that EDT$EDIT is to edit. The in_file 
argument is the address of a descriptor pointing to this file specification. The 
string that you enter in this calling sequence is passed to the fileio routine to 
open the primary input file. This is the only required argument. 


out—file 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 
read only 
by descriptor 


File specification of the output file that EDT$EDIT creates. The out_file 
argument is the address of a descriptor pointing to this file specification. The 
default is that the input file specification is passed to the fileio routine to 
open the output file for the EXIT command. 


com—file 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 
read only 
by descriptor 


File specification of the start-up command file to be executed when EDT is 
invoked. The com—file argument is the address of a descriptor pointing to 
this file specification. The com_file string is passed to the fileio routine to 
open the command file. The default is the same as that for EDT command 
file defaults. 
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EDT$EDIT 


jou—file 

VMS Usage: 
type: 
access: 
mechanism: 


char-string 

character-coded text string 
read only 
by descriptor 


File specification of the journal file to be opened when EDT is invoked. 
The jou—file argument is the address of a descriptor pointing to this file 
specification. The jou—file string is passed to the fileio routine to open the 
journal file. The default uses the same file name as in_file. 


options 

VMS Usage: 
type: 
access: 
mechanism: 


mask_Jongword 
aligned bit string 
read only 
by reference 


Bit vector specifying options for the edit operation. The options argument 
is the address of an aligned bit string containing this bit vector. Only bits 
<5:0> are currently defined; all others must be 0 . The default options 
have all bits set to 0 . This is the same as the default setting when you 
invoke EDT to edit a file from DCL. 


Symbols and their descriptions follow: 


EDT$M_RECOVER 


EDT$M_COMMAND 


EDT$M_NOJOURNAL 

EDT$M_NOOUTPUT 


If set, bit <0> causes EDT to read the journal file 
and execute the commands in it, except for the EXIT or 
QUIT commands, which are ignored. Once the journal 
file commands have been processed, editing continues 
normally. If bit <0> is set, the fileio routine will 
be asked to open the journal file for both input and 
output; otherwise fileio will only be asked to open the 
journal file for output. Bit <0> corresponds to the 
/RECOVER qualifier on the EDT command line. 

If set, bit < 1 > causes EDT to signal if the start¬ 
up command file cannot be opened. When bit 
< 1 > is 0 , EDT will intercept the signal from the 
fileio routine indicating that the start-up command 
file could not be opened. Then, EDT will simply 
proceed with the editing session, without reading 
any start-up command file. If no command file name 
is supplied with the call to the EDTSEDIT routine, 

EDT tries to open SYS$LIBRARY:EDTSYS.EDT or, if 
that fails, EDTINI.EDT. Bit <1> corresponds to the 
/COMMAND qualifier on the EDT command line. If 
EDT$M_NOCOMMAND (bit <4> ) is set, bit <1> is 
overridden since bit <4> prevents EDT from trying 
to open a command file. 

If set, bit <2> prevents EDT from opening the journal 
file. Bit <2> corresponds to the /NOJOURNAL or 
/READ-ONLY qualifier on the EDT command line. 

If set, bit <3> prevents EDT from using the input 
file name as the default output file name. Bit <3> 
corresponds to the /NOOUTPUT or /READ-ONLY 
qualifier on the EDT command line. 
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EDT$EDIT 


EDT$M_NOCOMMAND If set, bit <4> prevents EDT from opening a start¬ 
up command file. Bit <4> corresponds to the 
/NOCOMMAND qualifier on the EDT command line. 

EDT$M_NOCREATE If set, bit <5> causes EDT to return to the caller if 

the input file is not found. The status returned is the 
error code EDT$_INPFILNEX. 


fileio 

VMS Usage: 
type: 
access: 
mechanism: 


vector_longword—unsigned 
bound procedure value 
function call 
by reference 


User-supplied routine that is called by EDT to perform file I/O functions. 

The fileio argument is the address of a bound procedure value containing the 
user-supplied routine. When you do not need to intercept any file I/O, either 
use the entry point EDT$FILEIO for this argument or omit it. When you only 
need to intercept some amount of file I/O, call the EDT$FILEIO routine for 
the other cases. 


To avoid confusion, note that EDT$FILEIO is a routine provided by EDT 
whereas FILEIO is a routine provided by the user. 

In order to accommodate routines written in high-level languages that do 
up-level addressing, this argument must have a data type of BPV (bound 
procedure value). BPV is a two-longword entity in which the first longword 
contains the address of a procedure entry mask and the second longword is 
the environment value. When the bound procedure is called, EDT loads the 
second longword into Rl. If you use EDT$FILEIO for this argument, set the 
second longword to <0> . You can simply pass a <0> for the argument, 
and EDT will set up EDT$FILEIO as the default and set the environment 
word to 0 . 


workio 

VMS Usage: 
type: 
access: 
mechanism: 


vector_longword_unsigned 
bound procedure value 
function call 
by reference 


User-supplied routine that is called by EDT to perform I/O between the work 
file and EDT. The workio argument is the address of a bound procedure 
value containing the user-supplied routine. Work file records are addressed 
only by number and are always 512 bytes long. If the user does not need to 
intercept work file I/O, you can use the entry point EDT$WORKIO for this 
argument or it can be omitted. 

In order to accommodate routines written in high-level languages that do 
up-level addressing, this argument must have a data type of BPV (bound 
procedure value). This means that EDT will load Rl with the second 
longword addressed before calling it. If EDT$WORKIO is used for this 
argument, set the second longword to 0 . You can simply pass a 0 for this 
argument, and EDT will set up EDT$WORKIO as the default and set the 
environment word to 0. 
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xlate 

VMS Usage: vector_longword_unsigned 
type: bound procedure value 

access: function call 

mechanism: by reference 

User-supplied routine that EDT calls when it encounters the nokeypad 
command XLATE. The xlate argument is the address of a bound procedure 
value containing the user-supplied routine. XLATE allows you to gain control 
of your EDT session. If you do not need to have control of EDT during the 
editing session, you can use the entry point EDT$XLATE for this argument or 
you can omit it. 

In order to accommodate routines written in high-level languages that do 
up-level addressing, this argument must have a data type of BPV (bound 
procedure value). This means that EDT will load R1 with the second 
longword addressed before calling it. If EDT$XLATE is used for this 
argument, set the second longword to 0 . You can simply pass a 0 for 
this argument, and EDT will set up EDT$XLATE as the default and set the 
environment word to 0 . 

DESCRIPTION 

If the EDT session is terminated by EXIT or QUIT, the status will be a 
successful value (bit <0> =1). If the session is terminated because the file 
was not found and if the /NOCREATE qualifier was in effect, the failure code 
EDT$_INPFILNEX is returned. In an unsuccessful termination caused by an 
EDT error, a failure code corresponding to that error is returned. Each error 
status from the fileio and workio routines is explained separately. 

Three of the arguments to the EDT$EDIT routine, fileio, workio, and xlate 
are the entry point names of user-supplied routines. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Successful completion 

EDT$_INPFILNEX /NOCREATE specified and input file does not exit 

Any condition values returned by user-supplied routines. 
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FILEIO 

Is a user-supplied routine that performs file I/O functions. It cannot 
be independently called and is called specifying it as an argument in 
the EDT$EDIT routine. 

FORMAT 

FILEIO code,stream,record,rhb 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

A VAX/VMS status code that the user's FILEIO routine returns to EDT$EDIT. 
The fileio argument is a longword containing the status code. The only 
failure code that is normally returned is RMS$_EOF from a GET call. All 
other VAX RMS errors are signaled, not returned. The VAX RMS signal 
should include the file name and both longwords of the RMS status. Any 
errors detected with the FILEIO routine can be indicated by setting status to 
an error code. That special error code will be returned to the program by the 
EDT$EDIT routine. There is a special status value EDT$_NONSTDFIL for 
nonstandard file opening. 

Condition values are returned in RO. 

ARGUMENTS 

code 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

A code from EDT that specifies what function the FILEIO routine is to 
perform. The code argument is the address of a longword integer containing 
this code. The valid function codes follow. 

EDT$K_OPEN_INPUT The record argument names a file that is to 

be opened for input. The rhb argument is 
the default file name. 

EDT$K_OPEN_OUTPUT_SEQ The record argument names a file that is to 

be opened for output as a sequenced file. 
The rhb argument is the default file name. 

EDT$K_OPEN_OUTPUT_NOSEQ The record argument names a file that is to 

be opened for output. The rhb argument is 
the default file name. 

EDT$K_OPEN_IN_OUT The record argument names a file that is to 

be opened for both input and output. The 


rhb argument is the default file name. 
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EDT$K_GET The record argument is to be filled with 

data from the next record of the file. If the 
file has record prefixes, rhb is filled with 
the record prefix. If the file has no record 
prefixes, rhb is not written. When you 
attempt to read past the end of file, status 
is set to RMS$_EOF. 

EDT$K_PUT The data in the record argument is to be 

written to the file as its next record. If the 
file has record prefixes, the record prefix 
is taken from the rhb argument. For a file 
opened for both input and output, 
EDT$K_PUT is valid only at the end of 
the file, indicating that the record is to be 
appended to the file. 

EDT$K_CLOSE_DEL The file is to be closed and then deleted. 

The record and rhb arguments are not used 
in the call. 

EDT$K_CLOSE The file is to be closed. The record and 

rhb arguments are not used in the call. 


stream 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

A code from EDT that indicates which file is being used. The stream 
argument is the address of a longword integer containing the code. The 
valid codes are: 


EDT$K_COMMAND_FILE 

EDT$K_INPUT_FILE 

EDT$K_INCLUDE_FILE 


EDT$K_JOURNAL_FILE 


EDT$K_OUTPUT_FILE 

EDT$K_WRITE_FILE 


The command file. 

The primary input file. 

The secondary input file. Such a file is opened in 
response to an INCLUDE command. It is closed 
when the INCLUDE command is complete and will 
be reused for subsequent INCLUDE commands. 

The journal file. If bit 0 of the options is set, it 
is opened for both input and output and is read 
completely. Otherwise, it is opened for output 
only. Once it has been read or opened for output 
only, it is used for writing. On a successful 
termination of the editing session, the journal file is 
closed and deleted. EXIT/SAVE and QUIT/SAVE 
close the journal file without deleting it. 

The primary output file. It is not opened until the 
EXIT command is given. 

The secondary output file. Such a file is opened 
in response to a WRITE or PRINT command. It 
is closed when the command is complete and 
will be reused for subsequent WRITE or PRINT 
commands. 
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record 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 

modify 

by descriptor 


An argument that is a line of text passed by descriptor from EDT to the user- 
supplied FILEIO routine. The record argument is the address of a descriptor 
pointing to this argument. The code argument determines how the record 
argument is used. When the code argument starts with EDT$K_OPEN, the 
record is a file name. When the code argument is EDT$K_GET, the record 
is a place to store the record that was read from the file. For code argument 
EDT$K_PUT, the record is a place to find the record to be written to the file. 
This argument is not used if the code argument starts with EDT$K_CLOSE. 

Note that for EDT$K_GET, EDT uses a dynamic or varying string descriptor; 
otherwise, EDT has no way of knowing the length of the record being read. 
EDT uses only string descriptors that can be handled by the RTL (Run-Time 
Library) routine STR$COPY_DX. 


rhb 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 

modify 

by descriptor 


This argument also depends on the code argument. When the code argument 
starts with EDT$K_OPEN, the rhb argument is the default file name. When 
the code is EDT$K_GET and the file has record prefixes, the prefixes are 
put in this argument. When the code is EDT$K__PUT and the file has 
record prefixes, the prefixes are taken from this argument. Like the record 
argument, EDT uses a dynamic or varying string descriptor for EDT$K_GET, 
and will use only string descriptors that can be handled by the RTL routine 
STR$COPY_DX. 


DESCRIPTION If you do not need to intercept any file I/O, you can use the entry point 

EDT$FILEIO for this argument or you can omit it. If you only need to 

intercept some file I/O, call the EDT$FILEIO routine for the other cases. 

When you use EDT$FILEIO as a value for the fileio argument, files are 

opened as follows: 

• The record argument is always the RMS file name. 

• The rhb argument is always the RMS default file name. 

• There is no related name for the input file. 

• The related name for the output file is the input file with OFP (output file 
parse). EDT passes either the input file name, the output file name, or the 
name from the EXIT command in the record argument. 

• The related name for the journal file is the input file name with the OFP 
(output file parse) RMS bit set. 

• The related name for the INCLUDE file is the input file name with the 
OFP set. This is unusual because the file is being opened for input. 
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CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

EDT$_NONSTDFIL 

RMS$_EOF 


Successful completion. 

File is not in standard text format. 
End of file on a GET. 
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WORKIO 

Is a user-supplied routine that is called by EDT when it needs 
temporary storage for the file being edited. It cannot be 
independently called and is called by specifying it as an argument in 
the EDT$EDIT routine. 

FORMAT 

WORKIO code jecordno ,record 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by immediate value 

Longword value returned as a VAX/VMS status code. It is normally a success 
code, since all VAX RMS errors should be signaled. The signal should 
include the file name and both longwords of the VAX RMS status. Any errors 
detected within work I/O can be indicated by setting status to an error code, 
which will be returned by the EDT$EDIT routine. 

Condition value returned in RO. 

ARGUMENTS 

code 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

An argument that refers to the operation to be performed. The code argument 
is the address of a longword integer containing this argument. The valid 
function codes are: 


Function Code Descriptors 

EDT$K_OPEN_IN_OUT Open the work file for both input and output. Neither 

the record nor recordno argument is used. 

EDT$K_GET Read a record. The recordno argument is the number 

of the record to read. The record argument gives the 
location where the record is to be stored. 

EDT$K_PUT Write a record. The recordno argument is the 

number of the record to write. The record argument 
tells the location of the record to be written. 

EDT$K_CLOSE_DEL Close the work file. After a successful close, the file 

is deleted. Neither the record nor recordno argument 


is used 
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recordno 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

This argument is not used for open or close calls. The recordno argument is 
the address of a longword integer containing this argument. For EDT$K_GET 
and EDT$K_PUT, this argument contains the number of the record to be read 
or written. EDT always writes a record before reading that record. 

record 

VMS Usage: char_string 
type: character string 

access: modify 

mechanism: by descriptor 

This argument is not used for open or close calls. For read operations, record 
contains the location of the record to be read. For write operations, record 
tells where the record is to be written. This argument always refers to a 
512-byte string during GET and PUT calls. 

DESCRIPTION 

Work file records are addressed only by number and are always 512 bytes 
long. If you do not need to intercept work file I/O, you can use the entry 
point EDT$WORKIO for this argument or it can be omitted. 

CONDITION 

VALUES 

RETURNED 

SSS—NORMAL Successful completion. 
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XLATE 

Is a user-supplied routine that EDT calls when it encounters the 
nokeypad command XLATE. It cannot be independently called and 
is called by specifying it as an argument in the EDT$EDIT routine. 

FORMAT 

XLATE string 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword value returned as a VAX/VMS status code. It is normally a success 
code. If the XLATE routine cannot process the passed string for some reason, 
it sets status to an error code. Returning an error code from the XLATE 
routine will abort the current key execution and display the appropriate error 
message. 

Condition value returned in RO. 

ARGUMENT 

string 

VMS Usage: char_string 
type: character-coded text string 

access: modify 

mechanism, by descriptor 

Text string passed to the nokeypad command XLATE. You can use the 
nokeypad command XLATE by defining a key to include in its definition the 
following command: 

XLATEtext~Z 

The text is passed by the string argument. The string argument will be one 
that can be handled by the RTL (Run-Time Library) routine STR$COPY_DX. 

This argument is also a text string returned to EDT. The string is made up of 
nokeypad commands that EDT will execute. 

DESCRIPTION 

The nokeypad command XLATE allows you to gain control of the EDT 
session. (See the VAX EDT Reference Manual for more information about the 
XLATE command.) If you do not need to gain control of EDT during the 
editing session, you can use the entry point EDT$XLATE for this argument or 
you can omit it. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Successful completion. 
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File Definition Language (FDL) Routines 


7.1 Introduction to FDL Routines 

This section describes the File Definition Language (FDL) routines. These 
routines perform many of the functions of RMS File Definition Language. 

The FDL$CREATE routine is the FDL routine most likely to be called from 
a high-level language. It creates a file from an FDL specification and then 
closes the file. 

The following three FDL routines provide a way to specify all the options 
RMS allows when it executes Create, Open, or Connect operations. They also 
allow you to specify special processing options required for your applications. 

The FDL$GENERATE routine produces an FDL specification by interpreting 
a set of RMS control blocks. It then writes the FDL specification either to an 
FDL file or to a character string. 

The FDL$PARSE routine parses an FDL specification, allocates RMS control 
blocks, and fills in (populates) the relevant fields. 

The FDL$RELEASE routine deallocates the virtual memory used by the RMS 
control blocks created by FDL$PARSE. 

These routines cannot be called from AST level. 


7.2 Examples of Using the FDL Routines 

The following example shows how to use the FDL$CREATE routine in a 
FORTRAN program. 


FDL—1 






File Definition Language (FDL) Routines 

Examples of Using the FDL Routines 


Example FDL-1 Using FDL$CREATE in a FORTRAN Program 


* 


♦ 

* 

* 


* 

♦ 


1000 

2000 


This program calls the FDL$CREATE routine. It 
creates an indexed output file named NEW_MASTER.DAT 
from the specifications in the FD1 file named 
INDEXED.FDL. You can also supply a default filename 
and a result name (that receives the name of the 
created file. The program also returns all the 
statistics. 


IMPLICIT INTEGERS 

EXTERNAL LIB$GET_LUN, 

CHARACTER IN_FILE*11 

1 0UT_FILE*14 

1 DEF_FILE*11 

1 RES_FILE*50 

INTEGERS FIDBLK(3) 

1 = 1 

STATUS = FDL$CREATE (IN_FILE,OUT_FILE, 

DEF.FILE,RES.FILE.FIDBLK,,) 

IF (.NOT. STATUS) CALL LIB$ST0P C/,VAL(STATUS)) 


(A - Z) 

FDL$CREATE 
/'INDEXED.FDL'/, 

/'NEW.MASTER.DAT'/, 
/'DEFAULT.FDL'/, 

/ 0 . 0 . 0 / 


STATUS=LIB$GET_LUN(LOG.UNIT) 

OPEN (UNIT=LOG_UNIT,FILE=RES_FILE,STATUS*'OLD') 
CLOSE (UNIT=LOG_UNIT, STATUS*'KEEP') 


WRITE (6,1000) (RES.FILE) 

WRITE (6,2000) (FIDBLK (I), 1*1,3) 

FORMAT (IX.'The result filename is: ',A50) 

FORMAT (/IX,'FID-NUM: '.15/. 

1 lX.'FID-SEQ: ',15/, 

1 lX.'FID-RVN: M5) 


END 


The following example shows how to use the FDL$PARSE and 
FDL$RELEASE routines in a MACRO program. 
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Example FDL-2 Using FDL$PARSE and FDL$RELEASE in a 

MACRO Program 


This program calls the FDL utility routines FDL$PARSE and 
FDLlRELEASE. First, FDL$PARSE parses the FDL specification 
PART.FDL. Then the data file named in PART.FDL is accessed 
using the primary key. Last, the control blocks allocated 
by FDL$PARSE are released by FDLlRELEASE. 


.TITLE FDLEXAM 


.PSECT DATA,WRT,NOEXE 


MY.FAB: 

MY.RAB: 

FDL.FILE: 

REC_SIZE=80 

LF=10 

REC.RESULT: 


REC.BUFFER: 

HEADING: 


.LONG 0 
.LONG 0 

.ASCID /PART.FDL/ ; Declare FDL file 


.LONG REC.SIZE 
.ADDRESS REC.BUFFER 
.BLKB REC.SIZE 

.ASCID /ID PART SUPPLIER COLOR /<LF> 


.PSECT CODE 


Declare the external routines 


.EXTRN 

FDL$PARSE, - 



FDLlRELEASE 


• 

.ENTRY 

FDLEXAM 

, ~M<> 

; Set up entry mask 


PUSHAL 

MY.RAB 

; Get set up for call with 


PUSHAL 

MY.FAB 

; addresses to receive the 


PUSHAL 

FDL.FILE 

; FAB and RAB allocated by 


CALLS 

#3,G~FDL|PARSE 

; FDLIPARSE 


BLBS 

RO.KEYO 



BRW 

ERROR 


9 

KEYO: 

MOVL 

MY.FAB,RIO 

; Move address of FAB to RIO 


MOVL 

MY.RAB,R9 

; Move address of RAB to R9 


MOVL 

♦REC.SIZE,RABIW.USZ(R9) 


MOVAB 

REC.BUFFER,RABlL.UBF(R9) 


I0PEN 

FAB=(RIO) 

; Open the file 


BLBC 

RO,ERROR 



ICONNECT RAB=(R9) 

; Connect to the RAB 


BLBC 

RO.ERROR 



PUSHAQ 

HEADING 

; Display the heading 


CALLS 

#1,G~LIB$PUT_OUTPUT 



BLBC 

RO.ERROR 



(Continued on next page) 
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Example FDL—2 (Cont.) Using FDL$PARSE and FDL$RELEASE 

in a MACRO Program 


GET.REC: 

$GET 

RAB=(R9) 

; Get a record 


CMPL 

#RMS$_EOF,RO 

; If not end of file. 


BEQLU 

CLEAN 

; continue 


BLBC 

RO,ERROR 



MOVZWL 

RAB$W_RSZ(R9),REC_RESULT ; Move a record into 


PUSHAL 

REC.RESULT 

; the buffer 


CALLS 

#1,G~LIB$PUT_OUTPUT 

; Display the record 


BLBC 

RO.ERROR 



BRB 

GET.REC 

; Get another record 

CLEAN: 

$CLOSE 

FAB=(RIO) 

; Close the FAB 


BLBC 

RO,ERROR 



PUSHAL 

MY.RAB 

; Push RAB addr on stack 


PUSHAL 

MY.FAB 

; Push FAB addr on stack 


CALLS 

#2,G ~FDLlRELEASE 

; Release control blocks 


BLBC 

RO,ERROR 



BRB 

FINI 


ERROR: 

PUSHL 

RO 



CALLS 

#1,G~LIB$SIGNAL 



$CLOSE 

FAB=(R10) 


RAB.ERROR: 

PUSHL 

RAB$L_STV(R9) 



PUSHL 

RAB$L_STS(R9) 



BRB 

RMS.ERR 


FAB.ERROR: 

PUSHL 

FAB$L_STV(RIO) 



PUSHL 

FAB$L_STS(RIO) 


9 

RMS.ERR: 

CALLS 

#2,G~LIB$SIGNAL 



BRB 

FINI 


FINI: 

RET 




.END FDLEXAM 



The following example shows how to use the FDL$GENERATE routine in a 
VAX PASCAL program. 
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Example FDL—3 Using FDL$PARSE and FDL$GENERATE in a 
VAX PASCAL Program 


[INHERIT ('SYS$LIBRARY:STARLET')] 

PROGRAM FDLexample (input,output,order_master); 


(* This program fills in its own FAB, RAB, and 
(* XABs by calling FDL$PARSE and then generates 
(* an FDL specification describing them. 

(* It requires an existing input FDL file 
(* (TESTING.FDL) for FDL$PARSE to parse. 

TYPE 

(*+ 

(* FDL CALL INTERFACE CONTROL FLAGS 
(*- 


*) 

*) 

*) 

*) 

*) 


*) 

*) 

*) 


$BIT1 = [BIT(1).UNSAFE] BOOLEAN; 

FDL2$TYPE = RECORD CASE INTEGER OF 
1: (FDL$_FDLDEF_BITS : [BYTE(l)] RECORD END; 

); 

2: (FDL$V_SIGNAL : [POS(O)] $BIT1; 

(* Signal errors; don't return *) 

FDL$V_FDL_STRING : [P0S(1)] $BIT1; 

(* Main FDL spec is a char string *) 

FDL$V_DEFAULT_STRING : [P0S(2)] $BIT1; 

(* Default FDL spec is a char string *) 
FDL$V_FULL.OUTPUT : [P0S(3)] $BIT1; 

(* Produce a complete FDL spec *) 

FDL$V_$CALLBACK : [P0S(4)] $BIT1; 

(* Used by EDIT/FDL on input (DEC only) *) 

) 

END; 

mail_order = RECORD 


order.num : [KEY(0)] INTEGER; 
name : PACKED ARRAY[1..20] OF CHAR; 
address : PACKED ARRAY[i..20] OF CHAR; 
city : PACKED ARRAY[1..19] OF CHAR; 
state ; PACKED ARRAY[1..2] OF CHAR; 
zip.code : [KEY(l)] PACKED ARRAY[1..5] 
OF CHAR; 

item.num : [KEY(2)] INTEGER: 
shipping : REAL; 

END; 


order.file = [UNSAFE] FILE OF mail.order; 
ptr.to.FAB = ~FAB$TYPE; 
ptr.to.RAB = “RAB$TYPE; 
byte = 0..255; 


(Continued on next page) 
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Example FDL-3 (Cont.) Using FDL$PARSE and 

FDL$GENERATE in a VAX PASCAL 
Program 


VAR 


order_master 

flags 

order.rec 

temp.FAB 

temp_RAB 

status 


order.file; 
FDL2$TYPE; 
mail_order 
ptr_to_FAB 
ptr_to_RAB 
integer; 


FUNCTION FDL$PARSE 

(y.STDESCR FDL.FILE : PACKED 
OF CHAR; 

VAR FAB.PTR : PTR_T0_FAB; 
VAR RAB.PTR : PTR.TO.RAB) : 


ARRAY [L..U:INTEGER] 


INTEGER; EXTERN; 


FUNCTION FDL$GENERATE 

OiREF FLAGS : FDL2$TYPE; 

FAB.PTR : PTR.TO.FAB; 

RAB.PTR : PTR.TO.RAB; 

XSTDESCR FDL.FILE.DST : PACKED ARRAY [L..U:INTEGER] 
OF CHAR) : INTEGER; 

EXTERN; 


BEGIN 

status := FDL$PARSE ('TESTING',TEMP_FAB,TEMP.RAB); 


flags::byte := 0; 

status FDL$GENERATE (flags. 

temp.FAB, 
temp.RAB, 

'SYS$OUTPUT: 


); 


END. 


7.3 FDL Routines 


The following pages describe the individual FDL routines in routine template 
format. 
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FDL$CREATE—Create 



Creates a file from an FDL specification and then closes the file. 

FORMAT 

FDL$CREATE fdl—desc [,file—name][,default—name] 
[,result—name] [, fid—block] [, flags] 

[, stmnt—num] [,retlen] [, sts] [, stv] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

fdl—desc 

VMS Usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor-fixed length string descriptor 

The name of a file that contains the FDL specification or the actual FDL 
specification to be parsed. The fdl—desc argument is the address of a 
character string descriptor pointing to this information. 

If the FDL$V_FDL—STRING flag is set in the mask argument, FDL$CREATE 
interprets this argument as an FDL specification in string form. Otherwise, 
FDL$CREATE interprets this argument as a file name. 

file—name 

VMS Usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor-fixed length string descriptor 

The name of the VAX RMS file to be created using the FDL specification. The 
file—name argument is the address of a character string descriptor pointing to 
the VAX RMS file name. This name overrides the default—name parameter 
given in the FDL specification. 

This argument is optional. 


FDL—7 










File Definition Language (FDL) Routines 

FDL$CREATE 


default-name 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 
read only 

by descriptor-fixed length string descriptor 


The default name of the file to be created using the FDL specification. The 
default—name argument is the address of a character string descriptor 
pointing to the default file name. This name overrides any name given in the 
FDL specification. 

This argument is optional. 


result—name 


VMS Usage: 
type: 
access: 
mechanism: 


char—string 

character-coded text string 
write only 

by descriptor-fixed length string descriptor 


The resultant name of the file created by FDL$CREATE. The result—name 
argument is the address of a character string descriptor that receives the 
resultant file name. 


This argument is optional. 


fid—block 


VMS Usage: 
type: 
access: 
mechanism: 


vector—longword—unsigned 
longword (unsigned) 
write only 
by reference 


The file identification of the VAX RMS file created by FDL$CREATE. The 
fid—block argument is the address of an array of longwords that receives 
the VAX RMS file identification information. The first longword contains the 
FID—NUM, the second contains the FID_SEQ, and the third contains the 
FID—RVN. Their meanings are as follows: 


FID—NUM is the location of the file on the disk. Its value can range from 1 up 
to the number of files the disk can hold. 

FID_SEQ is the file sequence number, which is the number of times the file 
number has been used. 

FID—RVN is the relative volume number, which is the volume number of the 
volume on which the file is stored. If the file is not stored on a 
volume set, the relative volume number is 0 . 


This argument is optional. 


flags 

VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Flags (or masks) that control how the fdl_desc argument is interpreted and 
how errors are signaled. The flags argument is the address of a longword 
containing the control flags (or a mask). If this argument is omitted or is 
specified as zero, no flags are set. The flags and their meanings are described 
below. 
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Flag 

Description 

FDL$ V_FDL —STRING 

Interprets the fdl_desc argument as an FDL 

specification in string form. By default, the fdl_desc 

argument is interpreted as the file name of an FDL file. 

FDL$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signaled. 


stmnt—num 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


The FDL statement number. The stmnt—num argument is the address of a 
longword that receives the FDL statement number. If the routine completes 
successfully, the stmnt—num argument is the number of statements in the 
FDL specification. If the routine does not complete successfully, the 
stmnt _num argument receives the number of the statement that caused 
the error. In general, however, line numbers and statement numbers are 
not the same. Null statements (blank lines) are not counted. Also, an FDL 
specification in string form has no 'Tines." 

This argument is optional. 


retlen 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


The number of characters returned in the result—name argument. The retlen 
argument is the address of a longword that receives this number. 

This argument is optional. 


sts 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword—unsigned 
write only 
by reference 


The VAX RMS status value FAB$L_STS. The sts argument is the address 
of a longword that receives the VAX RMS status value FAB$L_STS from 
SYS$CREATE. 


stv 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


The VAX RMS status value FAB$L_STV. The stv argument is the address 
of a longword that receives the VAX RMS status value FAB$L_STV from 
SYSSCREATE. 
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DESCRIPTION FDL$CREATE calls the FDL$PARSE routine to parse the FDL specification. 

The FDL specification can be either in a file or a character string. 
FDL$CREATE opens (creates) the specified VAX RMS file, and then closes it 
without putting any data in it. 

FDL$CREATE will not create the output file if an error status is either 
returned or signaled. The return codes, which follow, are defined in the 
modules $FDLDEF and $RMSDEF. 


CONDITION SS$_NORMAL 

VALUES FDL$_ABKW 

RETURNED fdl$_abprikw 

FDL$_BADLOGIC 

FDL$_CLOSEIN 

FDL$_CLOSEOUT 

FDL$_CREATE 

FDL$_CREATED 

FDL$_CREATED_STM 

FDL$_FDLERROR 

FDL$_ILL_ARG 

FDLS—INSVIREM 

FDL$_INVBLK 

FDL$_MULPRI 

FDL$_OPENFDL 

FDL$_OPENIN 

FDL$_OPENOUT 

FDL$_OUT ORDER 

FDL$_READERR 

FDL$_RFLOC 

FDL$_SYNTAX 

FDL$_UNPRIKW 

FDL$_UNQUAKW 

FDL$_UNSECKW 

FDL$_VALERR 

FDL$_VALPRI 

FDL$_WARNING 

FDL$_WRITEERR 

RMS$_ACT 

RMS$_CRE 

RMS$_CREATED 

RMSS—DNF 


Normal successful completion. 

Ambiguous keyword in statement n. 

Ambiguous primary keyword in statement n. 
Internal logic error detected. 

Error closing file specification as input. 

Error closing file specification as output. 

Error creating file specification. 

File specification created. 

File specification has been created in stream 
format. 

Error parsing FDL file. 

Wrong number of arguments. 

Insufficient virtual memory. 

Invalid VAX RMS control block at virtual address n. 
Multiple primary definition in statement n. 

Error opening file specification. 

Error opening file specification as input. 

Error opening file specification as output. 

Key or area primary defined out of order in 
statement n. 

Error reading file specification. 

Unable to locate related file. 

Syntax error in statement n. 

Unrecognized primary keyword in statement n. 
Unrecognized qualifier keyword in statement n. 
Unrecognized secondary keyword in statement n. 
Specified value is out of legal range. 

Value required on primary in statement n. 

Parsed with warnings. 

Error writing file specification. 

File activity precludes operation. 

ACP file create failed. 

File was created, not opened. 

Directory not found. 
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RMS$_DNR 

RMS$_EXP 

RMS$_FEX 

RMS$_FLK 

RMS$_PRV 

RMS$_SUPERSEDE 

RMS$_WLK 


Device not ready or not mounted. 

File expiration date not yet reached. 

File already exists, not superseded. 

File currently locked by another user. 
Insufficient privilege or file protection violation. 
Created file superseded existing version. 
Device currently write locked. 
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FDL$GENERATE—Generate 



Produces an FDL specification and writes it either to an FDL file or to 
a character string. 

FORMAT 

FDL$GENERATE flags ,fab—pointer jab—pointer 

[, fdl—file—dst] [, fdl—file—resnam] 

[, fdl—str—dst] [,bad—blk—addr] 
[jetlen] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Flags (or masks) that control how the fdl__str_dst argument is interpreted and 
how errors are signalled. The flags argument is the address of a longword 
containing the control flags (or a mask). If this argument is omitted or is 
specified as zero, no flags are set. The flags and their meanings are described 
below. 


Flag Description 

FDL$V_FDI_STRING Interprets the fdl_str_dst argument as an FDL 

specification in string form. By default, the 
fdl_str_dst argument is interpreted as a file name of 
an FDL file. 

FDL$V_FULI_OUTPUT Includes the FDL attributes to describe all the bits 

and fields in the VAX RMS control blocks, including 
run-time options. If this flag is set, every VAX RMS 
field is inspected before being written. By default, 
only the FDL attributes that describe permanent file 
attributes are included (producing a much shorter FDL 
specification). 

FDL$V_SIGNAL Signals any error. By default, the status code is 

returned to the calling image. 
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fab—pointer 


VMS Usage: 
type: 
access: 
mechanism: 


address 

longword (unsigned) 
read only 
by reference 


The VAX RMS file access block (FAB). The fab—pointer argument is the 
address of a longword containing the address of an VAX RMS file access 
block (FAB). 


rab—pointer 


VMS Usage: 
type: 
access: 
mechanism: 


address 

longword (unsigned) 
read only 
by reference 


The VAX RMS record access block (RAB). The rab_pointer argument is the 
address of a longword containing the address of an VAX RMS record access 
block (RAB). 


fdl—file—dst 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 
read only 
by descriptor 


The name of the FDL file to be created. The fdl_file—dst argument is the 
address of a character string descriptor containing the file name of the FDL file 
to be created. If the FDL$V_FDL —STRING flag is set in the flags argument, 
this argument is ignored; otherwise, it is required. The FDL specification is 
written to the file named in this argument. 


fdl—file—resnam 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 
write only 

by descriptor-fixed length string descriptor 


The resultant name of the FDL file created. The fdl—file—resnam argument is 
the address of a variable character string descriptor that receives the resultant 
name of the FDL file created (if FDL$GENERATE is directed to create an FDL 
file). 

This argument is optional. 


fdlstr—dst 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 
write only 

by descriptor-fixed length string descriptor 


The FDL specification. The fdl—str—dst argument is the address of a variable 
character string descriptor that receives the FDL specification created. If 
the FDL$V_FDL—STRING bit is set in the flags argument, this argument is 
required; otherwise, it is ignored. 
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bad—blk—addr 


VMS Usage: 
type: 
access: 
mechanism: 


address 

longword (unsigned) 
write only 
by reference 


Address of an invalid VAX RMS control block. The bad—blk—addr argument 
is the address of a longword that receives the address of an invalid VAX 
RMS control block. If an invalid control block (a fatal error) is detected, this 
argument is returned; otherwise, it is ignored. 

This argument is optional. 


retlen 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


The number of characters received in either the fdl_file—resnam or the 
fdl_str_dst argument. The retlen argument is the address of a longword 
which receives this number. 


CONDITION SS$_NORMAL 

VALUES FDL$_INVBLK 

RETURNED Rms$_act 

RMSS—CONTROLC 

RMS$_CONTROLO 

RMS$_CONTROLY 

RMSS—DNR 

RMSS—EXT 

RMS$_OK_ALK 

RMS$_OK_DUP 

RMS$_OK_IDX 

RMS$_PENDING 

RMS$_PRV 

RMSS—REX 

RMS$_RLK 

RMSS—RSA 

RMS$_WLK 

SS$_ACCVIO 

STR$_FATINERR 

STR$_ILLSTRCLA 

STR$_INSVIRMEM 


Normal successful completion. 

Invalid VAX RMS control block at virtual address n. 
File activity precludes operation. 

Operation complete under CTRL/C. 

Output completed under CTRL/O. 

Operation completed under CTRL/Y. 

Device not ready or mounted. 

ACP file extend failed. 

Record is already locked. 

Record inserted had duplicate key. 

Index update error occurred. 

Asynchronous operation pending completion. 
Insufficient privilege or file protection violation. 
Record already exists. 

Target record currently locked by another stream. 
Record stream currently active. 

Device currently write locked. 

Access violation. 

Fatal internal error in Run-Time Library. 

Illegal string class. 

Insufficient virtual memory. 
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FDL$PARSE—Parse 



Parses an FDL specification, allocates VAX RMS control blocks 
(FABs, RABs, or XABs), and fills in the relevant fields. 

FORMAT 

FDL$PARSE fdlspec ,fdl—fab—pointer 

, fdl—rab—pointer [, flags] [, dflt—fdlspc] 
[,stmnt—num] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

fdlspec 

VMS Usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor-fixed length string descriptor 

The name of the FDL file or the actual FDL specification to be parsed. The 
fdl_spec argument is the address of a character string descriptor pointing to 
either the name of the FDL file or the actual FDL specification to be parsed. 

If the FDL$V_FDL—STRING flag is set in the flags argument, FDL$PARSE 
interprets this argument as an FDL specification in string form. Otherwise, 
FDL$PARSE interprets this argument as a file name of an FDL file. 

fdl—fab—,pointer 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of an RMS file access block (FAB). The fdl—fab_pointer argument is 
the address of a longword which receives the address of an RMS file access 
block (FAB). FDL$PARSE both allocates the FAB and fills in its relevant fields. 
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fdl—rab—pointer 


VMS Usage: 
type: 
access: 
mechanism: 


address 

longword (unsigned) 
write only 
by reference 


Address of an RMS record access block (RAB). The fdl_rab_pointer 
argument is the address of a longword which receives the address of an 
RMS record access block (RAB). FDL$PARSE both allocates the RAB and fills 
in its relevant fields. 


flags 

VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Flags (or masks) that control how the dflt_fdl_spc argument is interpreted 
and how errors are signaled. The flags argument is the address of a longword 
containing the control flags. If this argument is omitted or is specified as zero, 
no flags are set. The flags and their meanings are described below. 


Flag 

Description 

FDL$V_DEFAULT_STRING 

Interprets the dflt_fdl_spc argument as an FDL 
specification in string form. By default, the 
dflt_fdl_spc argument is interpreted as a file 
name of an FDL file. 

FDL$V_FDI_STRING 

Interprets the fdl_spec argument as an FDL 
specification in string form. By default, the 
fdl_spec argument is interpreted as a file name 
of an FDL file. 

FDL$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signaled. 


dflt—fdl—spc 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 
read only 

by descriptor-fixed length string descriptor 


The name of the default FDL file or the default FDL specification itself. The 
dflt__fdl_spc argument is the address of a character string descriptor pointing 
to either the default FDL file or the default FDL specification. If the 
FDL$V_DEFAULT_STRING flag is set in the flags argument, FDL$PARSE 
interprets this argument as an FDL specification in string form. Otherwise, 
FDL$PARSE interpets this argument as a file name of an FDL file. 

This argument allows you to specify default FDL attributes. In other words, 
FDL$PARSE processes the attributes specified in this argument, unless you 
override them with the attributes you specify in the fdl_spec argument. 

The FDL defaults can be coded directly into your program, typically with an 
FDL specification in string form. 
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CONDITION 

VALUES 

RETURNED 


This argument is optional. 


stmnt—num 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


The FDL statement number. The stmnt_num argument is the address of a 
longword that receives the FDL statement number. If the routine completes 
successfully, the stmnt_num argument is the number of statements in the 
FDL specification. If the routine does not complete successfully, the 
stmnt_num argument receives the number of the statement that caused the 
error. In general, however, line numbers and statement numbers are not the 
same. 


This argument is optional. 


SS$_NORMAL 

LIB$_BADBLOADR 

LIB$_BADBLOSIZ 

LIB$_INSVIRMEM 

RMSS—DNF 

RMSS—DNR 

RMS$_WCC 


Normal successful completion. 

Bad block address. 

Bad block size. 

Insufficient virtual memory. 

Directory not found. 

Device not ready or mounted. 

Invalid wild card context (WCC) value. 
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FDL$RELEASE—Release 



Deallocates the virtual memory used by the VAX RMS control blocks 
created by FDL$PARSE. You must use FDL$PARSE to populate the 
control blocks if you plan to deallocate memory with FDL$RELEASE 
later. 

FORMAT 

FDL$RELEASE [fab—pointer][,rab—pointer][,flags] 

[, badblk—addr] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

fab—pointer 

VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The file access block (FAB) to be deallocated using the LIB$FREE_VM system 
service. The fab_pointer argument is the address of a longword containing 
the address of the file access block (FAB). The FAB must be the same one 
returned by the FDL$PARSE routine. Any NAM and XAB blocks connected 
to the FAB are also released. 

This argument is optional. If this argument is omitted or is specified as zero, 
the FAB (and any associated NAM blocks and XABs) is not released. 

rab—pointer 

VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The record access block (RAB) to be deallocated using the LIB$FREE_VM 
system service. The rab_pointer argument is the address of a longword 
containing the address of the record access block (RAB). The address of the 
RAB must be the same one returned by the FDL$PARSE routine. Any XABs 
connected to the RAB are also released. 

This argument is optional. If this argument is omitted or is specified as zero, 
the RAB (and any associated XABs) is not released. 


FDL—18 








File Definition Language (FDL) Routines 

FDL$RELEASE 


CONDITION 

VALUES 

RETURNED 


flags 

VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


Flag (or mask) that controls how errors are signalled. The flags argument 
is the address of a longword containing the control flag (or a mask). If this 
argument is omitted or is specified as zero, no flag is set. The flag and its 
meaning are described below. 

FDL$V_SIGNAL Signals any error. By default, the status code is returned to 
the calling image. 


This argument is optional. 


badblk—addr 


VMS Usage: 
type: 
access: 
mechanism: 


address 

longword (unsigned) 
write only 
by reference 


The address of an invalid VAX RMS control block. The badblk_addr 
argument is the address of a longword which receives the address of an 
invalid VAX RMS control block. If an invalid control block (a fatal error) is 
detected, this argument is returned; otherwise, it is ignored. 


SS$_NORMAL 

FDL$_INVBLK 

LIB$_BADBLOADR 

RMS$_ACT 

RMS$_RNL 

RMS$_RSA 

SS$_ACCVIO 


Normal successful completion. 

Invalid VAX RMS control block at virtual address n. 
Bad block address. 

File activity precludes operation. 

Record not locked. 

Record stream currently active. 

Access violation. 
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Librarian (LBR) Routines 


8.1 



Introduction to LBR Routines 

Libraries are files that provide a convenient way to organize frequently used 
modules of code or text. The librarian routines allow you to create and 
maintain libraries and their modules, and to use the data stored in library 
modules. 

You can also create and maintain libraries at DCL level, using the DCL 
command LIBRARY. For details, see the VAX/VMS DCL Dictionary. 


8 . 1.1 




Types of Libraries 

You can use the librarian routines to maintain the following types of libraries: 

• Object libraries, which contain the object modules of frequently called 
routines. The VAX/VMS Linker searches specified object module libraries 
when it encounters a reference it cannot resolve in one of its input files. 
For more information on how the linker uses libraries, see the description 
of the VAX/VMS Linker Utility in the VAX/VMS Linker Reference Manual. 

An object library has a default file type of OLB and defaults the file type 
of input files to OBJ. 

• Macro libraries, which contain macro definitions used as input to the 
assembler. The assembler searches specified macro libraries when it 
encounters a macro that is not defined in the input file. See the VAX 
MACRO and Instruction Set Reference Volume for information on defining 
macros. 

A macro library has a default file type of MLB and defaults the file type of 
input files to MAR. 

• Help libraries, which contain modules of help messages that provide 
user information about a program. You can retrieve help messages at 
DCL level by executing the DCL command HELP, or in your program by 
calling the appropriate librarian routines. For information about creating 
help modules for insertion into help libraries, see the description of the 
Librarian Utility in the VAX/VMS Librarian Reference Manual. 

A help library has a default file type of HLB and defaults the file type of 
input files to HLP. 

• Text libraries, which contain any sequential record files that you want to 
retrieve as data for a program. For example, some compilers can retrieve 
program source code from text libraries. Each text file inserted into the 
library corresponds to one library module. Your programs can retrieve text 
from text libraries by calling the appropriate librarian routines. 

A text library has a default file type of TLB and defaults the file type of 
input files to TXT. 
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• Shareable image libraries, which contain the symbol tables of shareable 
images used as input to the linker. For information on how to create a 
shareable image library, see the descriptions of the librarian and linker 
utilities in the VAX/VMS Linker Reference Manual and the VAX/VMS 
Librarian Reference Manual. 

A shareable image library has a default type of OLB and defaults the file 
type of input files to EXE. 

• User-developed libraries, which have characteristics specified when you 
call the LBR$OPEN routine to create a new library. User-developed 
libraries allow you to use the librarian routines to create and maintain 
libraries that are not structured in the form assigned by default to the other 
library types. Note that you cannot use the DCL command LIBRARY to 
access user-developed libraries. 


8.1.2 Structure of Libraries 

You create libraries by executing the DCL command LIBRARY or by calling 
the LBR$OPEN routine. When object, macro, text, help, or shareable image 
libraries are created, the Library Utility structures them as described in 
Figures LBR-1 and LBR-2. User-developed libraries can be created only by 
calling LBR$OPEN; they are structured as described in Figure LBR-3. 


8.1.2.1 Library Headers 

Every library contains a library header that describes the contents of the 
library, for example, its type, size, version number, creation date, and number 
of indexes. You can retrieve data from a library's header by calling the 
LBR$GET_HEADER routine. 


8.1.2.2 Modules 

Each library module consists of a header and data. The data is the data you 
inserted into the library; the header associated with the data is created by 
the librarian routine and provides information about the module, including 
its type, attributes, and date of insertion into the library. You can read and 
update a module's header by calling the LBR$SET_MODULE routine. 


8.1.2.3 Indexes and Keys 

Libraries contain one or more indexes which can be thought of as directories 
of the library's modules. The entries in each index are keys. Each key 
consists of a key name and a module reference. The module reference is a 
pointer to the module's header record and is called that record's file address 
(RFA). Macro, text, and help libraries (see Figure LBR-1) contain only one 
index, called the module name table. The names of the keys in the index are 
the names of the modules in the library. 

Object and shareable image libraries (see Figure LBR-2) contain two indexes: 
the module name table and a global symbol table. The global symbol table 
consists of all the global symbols defined in the modules in the library. Each 
global symbol is a key in the index, and points to the module in which it was 
defined. 

If you need to point to the same module with several keys, you should create 
a user-developed library, which can have up to eight indexes. Each index 
consists of keys which point to the library's modules. 
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The librarian routines differentiate library indexes by numbering them, 
starting with 1. For all but user-developed libraries, the module name table 
is index number 1 and the global symbol table, if present, is index number 
2. The indexes in user-developed libraries are numbered by the user. When 
you access libraries that contain more than one index, you may have to call 
LBR$SET_INDEX to tell the librarian routines which index to use. 

Figure LBR-1 Structure of a Macro, Text, or Help Library 
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Figure LBR-2 Structure of an Object or Shareable Image Library 
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Figure LBR—3 Structure of a User-Developed Library 
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8.1.2.4 Summary of Routines 

All the librarian routines begin with the characters LBR$. Your programs 
can call these routines by using the VAX Procedure Calling and Condition 
Handling Standard, which is documented in the Introduction to VAX/VMS 
System Routines. When you call a librarian routine, you must provide 
whatever arguments the routine requires; when the routine completes 
execution, it returns a status value to your program. In addition to 
the condition values listed with the descriptions of each routine, some 
routines may return the success code SS$_NORMAL as well as various 
RMS or SS error codes. When you link programs that contain calls to 
librarian routines, the linker locates the routines during its default search 
of SYS$SHARE:LBRSHR. 

The librarian routines are described in detail in Section 3. Following are a list 
of the routines and a summary of their functions. 


Routine name 

LBR$CLOSE 
LBR$DELETE_DAT A 
LBR$DELETE_KEY 
LBR$FIND 

LBRSFLUSH 

LBR$GET_HEADER 

LBR$GET_HELP 

LBR$GET_HISTORY 

LBR$GET_INDEX 

LBR$GET_RECORD 

LBR$INI_CONTROL 

LBR$INSERT_KEY 

LBR$LOOKUP_KEY 

LBRSOPEN 

LBR$OUTPUT_HELP 

LBR$PUT_END 

LBR$PUT_HISTORY 

LBR$PUT_RECORD 

LBR$REPLACE_KEY 

LBR$RET_RMSSTV 


Function 

Closes an open library 

Deletes a specified module's header and data 
Deletes a key from a library index 

Finds a module by using an address which was returned 
by a preceding call to LBR$LOOKUP_KEY 

Writes the contents of modified blocks to the library 
file and returns the virtual memory that contained those 
blocks 

Retrieves information from the library header 
Retrieves help text from a specified library 

Retrieves library update history records and calls a 
user-supplied routine with each record returned 

Calls a routine to process modules associated with some 
or all of the keys in an index 

Reads a data record from the module associated with a 
specified key 

Initializes a control index that the librarian uses to 
identify a library 

Inserts a new key in the current library index 

Looks up a key in the current index 

Opens an existing library or creates a new one 

Retrieves help text from an explicitly named library 
or from user-supplied default libraries, and optionally 
prompts the user for additional help queries 

Terminates a sequence of records written to a module 
with LBR$PUT_RECORD 

Inserts a library update history record 

Writes a data record to the module associated with the 
specified key 

Replaces an existing key in the current library index 
Returns the last VAX RMS status value 
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Routine name Function 


LBR$SEARCH 

LBR$SET_INDEX 

LBR$SET_LOCATE 

LBR$SET_MODULE 

LBR$SET_MOVE 


Finds index keys that point to specified data 

Sets the index number to be used during processing of 
the library 

Sets librarian subroutine record access to locate mode 
Reads and optionally updates a module header 
Sets librarian subroutine record access to move mode 


8.2 Examples of Using the LBR Routines 

This section provides programming examples that show how to call LBR$ 
routines to create a library, insert a module into a library, extract a module 
from a library, and delete a module from a library. Although the examples do 
not use all the librarian routines, they do provide an introduction to the data 
structures needed and the calling syntax required to use any of the routines. 

For each library you want to work with, you must call LBR$INI—CONTROL 
and LBR$OPEN before calling any other routine (except 
LBR$OUTPUT_HELP). 

When you call LBR$INI—CONTROL, this routine sets up a control index (do 
not confuse this with a library index) that is used in the calls to the other 
librarian routines to identify the library to which the routine applies (because 
you may want your program to work with more than one library at a time). 
LBR$INI—CONTROL also specifies whether you want to create, read, or 
modify the library. 

After you call LBR$INI—CONTROL, you call LBR$OPEN to open the 
library and specify its type. When you finish working with a library, you 
should call LBR$CLOSE to close it. Remember to call LBR$INI_CONTROL 
again, if you wish to reopen the library. LBR$CLOSE deallocates all the 
memory associated with the library including the control index. The order in 
which you call the routines between LBR$OPEN and LBR$CLOSE depends 
upon the library operations you need to perform. You may want to call 
LBR$LOOKUP_KEY or LBR$GET_INDEX to find a key, then perform some 
operation on the module associated with the key. You can think of a module 
as being both the module itself and its associated keys. To access a module, 
you will first need to access a key that points to it, and to delete a module 
you will first need to delete any keys that point to it. 

The examples are written in VAX PASCAL. In VAX PASCAL, all data items, 
functions (such as the librarian routines), and procedures must be declared at 
the beginning of the program. Following the declarations is the executable 
section, which performs the actions of the program. The executable section 
makes extensive use of the structured control constructs IF-THEN-ELSE and 
WHILE-condition-DO. Note that code between a BEGIN END pair is treated 
as a unit. 

The listing of each example contains many comments (any code between 
the pair (* *) is a comment), and each listing is followed by notes about the 
program. The circled numbers in the notes are keyed to the circled numbers 
in the examples. 
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Example LBR-1 Creating A New Library Using VAX PASCAL 


PROGRAM createlibUNPUT,OUTPUT) ; 

(♦This program creates a text library*) 

TYPE (*Data type of*) 

Create.Array * ARRAY [1..20] OF INTEGER; (*create options array*) 

VAR (*Constants and return status error 

codes for LBRl.OPEN & LBR$INI.CONTROL. 
These are defined in SLBRDEF macro*) 
LBR$C_CREATE,LBR$C_TYP_TXT,LBR$_ILLCREOPT,LBR$_ILLCTL, O 

LBR$_ILLFMT,LBR$_NOFILNAM,LBR$_OLDMISMCH,LBR$_TYPMISMCH : 

[EXTERNAL] INTEGER; 


(♦Create options array codes. These 
are defined in $CREDEF macro*) 


CRE$L_TYPE.CRE$L_KEYLEN,CRE$L_ALLOC.CRE$L_IDXMAX,CRE$L_ENTALL, 
CRE$L_LUHMAX,CRE$L_VERTYP.CRE$L_IDXOPT,CRE$C_MACTXTCAS, 
CRE$C_VMSV3 : [EXTERNAL]INTEGER; 


Lib.Name : VARYING [128] OF CHAR; 
Options : Create_Array; 

File.Type : PACKED ARRAY [1..4] 

OF CHAR := '.TLB'; 
lib_index_ptr : UNSIGNED; 
status : UNSIGNED; 

(♦-♦-♦-♦-Function and Procedu 


(♦Name of library to create*) 
(♦Create options array*) 

(♦Character string that is default*) 
(♦file type of created lib file*) 
(♦Value returned in library init*) 
(♦Return Status for function calls*) 
Definitions-*-*-*-*) 


(♦Function that returns library 
control index used by librarian*) 
FUNCTION LBRIINI.CONTROL (VAR library.index: UNSIGNED; © 

func: UNSIGNED; 
typ: UNSIGNED; 

VAR namblk: ARRAY[1..u:INTEGER] 

OF INTEGER := 7.IMMED 0): 


INTEGER; EXTERN; 

(♦Function that creates/opens library*) 
FUNCTION LBRIOPEN (library.index: UNSIGNED; 

fns: [class.s]PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create.options: Create.Array; 

dns: [CLASS.S] PACKED ARRAY [13..u3:INTEGER] OF CHAR; 
rlfna: ARRAY [14.. u4: INTEGER] OF INTEGER : = 7.IMMED 0; 
rns: [CLASS.S] PACKED ARRAY [15..u5:INTEGER] OF CHAR :* 
'/,IMMED 0; 

VAR rnslen: INTEGER :* %IMMED 0): 

INTEGER; EXTERN; 

(♦Function that closes library*) 
FUNCTION LBRICLOSE (library.index: UNSIGNED): 

INTEGER; EXTERN; 

(♦Error handler to check error codes 
if open/create not successful*) 


(Continued on next page) 
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Example LBR-1 (Cont.) Creating A New Library Using VAX 

PASCAL 


PROCEDURE Open.Error; © 

BEGIN 

WRITELN('Open Not Successful'); (*Now check specific error codes*) 

IF status = IADDRESS(LBR$_ILLCREOPT) THEN 

WRITELN(' Create Options Not Valid Or Not Supplied'); 

IF status = IADDRESS(LBR$_ILLCTL) THEN 
WRITELN(' Invalid Library Index'); 

IF status = IADDRESS(LBR$_ILLFMT) THEN 

WRITELN(' Library Not In Correct Format'); 

IF status = IADDRESS(LBR$_NOFILNAM) THEN 

WRITELN(' Library Name Not Supplied'); 

IF status = IADDRESS(LBR$_OLDMISMCH) THEN 
WRITELN(' Old Library Conflict'); 

IF status = IADDRESS(LBR$_TYPMISMCH) THEN 
WRITELN(' Library Type Mismatch') 

END; (*of procedure Open_Error*) 

BEGIN (* *************** DECLARATIONS COMPLETE ************************* 

*************** main program begins HERE ********************** *) 

(♦Prompt for Library Name*) 

WRITEOLibrary Name: '); READLN(Lib.Name); 

(♦Fill Create Options Array. Divide 
by 4 and add 1 to get proper subscript*) 


Options[IADDRESS(CRE$L_TYPE) DIV 4 
Options[IADDRESS(CRE$L_KEYLEN) DIV 4 
Options[IADDRESS(CRE$L_ALLOC) DIV 4 
Options[IADDRESS(CRE$L_IDXMAX) DIV 4 
Options[IADDRESS(CRE$L_ENTALL) DIV 
Options[IADDRESS(CRE$L_LUHMAX) DIV 
Options[IADDRESS(CRE$L_VERTYP) DIV 
Options[IADDRESS(CRE$L_IDXOPT) DIV 


status := LBR$INI_CONTROL 


IF NOT ODD(status) THEN 
WRITELN( 

ELSE 

BEGIN 

status := LBR$0PEN 


END. 


1] := IADDRESS(LBR$C_TYP_TXT); 

1] := 31; © 

1 ] := 8 ; 

1 ] := 1 ; 

+ 1] := 96; 

+ 1 ] := 20 ; 

+ 1] := IADDRESS(CRE$C_VMSV3); 

+ 1] := IADDRESS(CRE$C_MACTXTCAS); 
(♦Initialize library control index*) 
(lib_index_ptr, © 

IADDRESS(LBR$C_CREATE). (*Create access*) 
IADDRESS(LBR$C_TYP_TXT)); (*Text library*) 
(*Check return status*) 

Initialization Failed') 

(♦Initialization was successful*) 
(♦Create and open the library*) 
(lib_index_ptr, 

Lib_Name, 

Options, O 

File.Type); 

IF NOT ODD(status) THEN (*Check return status*) 

Open.Error (*Call error handler*) © 

ELSE (*Open/create was successful*) 

BEGIN (*Close the library*) 

status := LBR$CLOSE(lib_index_ptr); 

IF NOT ODD(status) THEN (*Check return status*) 
WRITELN('Close Not Successful') 

END 

END 

(*of program creatlib*) 


(Continued on next page) 
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Example LBR-1 (Cont.) Creating A New Library Using VAX 

PASCAL 


O To gain access to these LBR$ symbols in your program, write the following 
two-line MACRO program: 

$LBRDEF GLOBAL 
.END 

Then assemble the program into an object module by executing the 
command: 

MACRO program-name 

Finally, link the resultant object module with the object module created 
when your source program is compiled or assembled. (Note: Pascal 
programmers alternatively may use the INHERIT attribute to include these 
symbols from SYS$LIBRARY:STARLET.PEN.) 

© To gain access to the CRE$ symbols, write a two-line MACRO program as 
described in item 1, substituting $CREDEF for $LBRDEF. 

© Start the declarations of the librarian routines that are used by the 
program. Each argument to be passed to the librarian is specified on a 
separate line, and includes the name (which just acts as a placeholder) and 
data type (for example: UNSIGNED, which means an unsigned integer 
value, and PACKED ARRAY OF CHAR, which means a character string). 

If the argument is preceded by VAR, then a value for that argument is 
returned by the librarian to the program. 

© Declare the procedure Open—Error, which is called in the executable 
section if the librarian returns an error when LBR$OPEN is called. 

Open—Error checks the librarian's return status value to determine the 
specific cause of the error. The return status values for each routine are 
listed in the descriptions of the routines. 

© Initialize the array called Options with the values the librarian needs to 
create the library. 

© Call LBR$INI—CONTROL, specifying that the function to be performed is 
create, and the library type is text. 

© Call LBR$OPEN to create and open the library; pass the Options array 
initialized in item 5 to the librarian. 

© If the call to LBR$OPEN was unsuccessful, call the procedure Open—Error 
(see item 4) to determine the cause of the error. 
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Example LBR-2 Inserting Module Into Library Using VAX 
PASCAL 


PROGRAM insertmod(INPUT,OUTPUT); 

(♦This program inserts a module into a library*) 

TYPE 

Rfa.Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 

VAR 


LBR$C_UPDATE, (*Constants for LBR$INI_CONTROL*) 

LBR$C_TYP_TXT, (*Defined in ILBRDEF macro*) 

LBR$_KEYNOTFND : [EXTERNAL] INTEGER;(*Error code for LBR$L00KUP_KEY*) 
Lib.Name : VARYING [128] OF CHAR; (*Name of library receiving module*) 
Module_Name : VARYING [31] OF CHAR; (*Name of module to insert*) 
Text_Data_Record : VARYING [255] OF CHAR; (*Record in new module*) 

Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*) 
lib_index_ptr : UNSIGNED; (*Value returned in library init*) 

status : UNSIGNED; (*Return status for function calls*) 

txtrfa.ptr : Rfa_Ptr; (*For key lookup and insertion*) 

Key.Not.Found : BOOLEAN := FALSE; (*True if new mod not already in lib*) 
(t-t-t-t-Function Definitions-*-*-*-*) 

(♦Function that returns library 
control index used by librarian*) 
FUNCTION LBR$INI_CONTROL (VAR library.index: UNSIGNED; 

func: UNSIGNED; 
typ: UNSIGNED; 

VAR namblk: ARRAY[1..u:INTEGER] 

OF INTEGER := DIMMED 0): 


INTEGER; EXTERN; 

(♦Function that creates/opens library*) 
FUNCTION LBR$0PEN (library.index: UNSIGNED; 

fns: [class.s]PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create.options: ARRAY [12..u2:INTEGER] OF INTEGER := 

'/.IMMED 0; 

dns: [CLASS.S] PACKED ARRAY [13..u3:INTEGER] OF CHAR 
:= '/.IMMED 0; 

rlfna: ARRAY [14.. u4: INTEGER] OF INTEGER := '/.IMMED 0; 
rns: [CLASS.S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
'/.IMMED 0; 

VAR rnslen: INTEGER := '/.IMMED 0): 

INTEGER; EXTERN; 

(♦Function that finds a key in index*) 
FUNCTION LBR$L00KUP_KEY (library.index: UNSIGNED; 

key.name:[CLASS.S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR; 

VAR txtrfa: Rfa.Ptr): 

INTEGER; EXTERN; 

(♦Function that inserts key in index*) 
FUNCTION LBR$INSERT.KEY (library.index: UNSIGNED; 

key.name:[CLASS.S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR; 

txtrfa: Rfa.Ptr): 

INTEGER; EXTERN; 

(♦Function that writes data records*) 


(Continued on next page) 
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Example LBR-2 (Cont.) Inserting Module Into Library Using 

VAX PASCAL 


FUNCTION LBR$PUT_RECORD (library.index: UNSIGNED; (*to modules*) 

textline:[CLASS.S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR; 

txtrfa: Rfa_Ptr): 

INTEGER; EXTERN; 

(♦Function that marks end of a module*) 
FUNCTION LBR$PUT_END (library.index: UNSIGNED): 

INTEGER; EXTERN; 

(♦Function that closes library*) 
FUNCTION LBR$CLOSE (library.index: UNSIGNED): 

INTEGER; EXTERN; 

BEGIN (* *************** DECLARATIONS COMPLETE ************************* 
*************** main program BEGINS HERE ********************** *) 

(♦Prompt for library name and 
module to insert*) 

WRITE('Library Name: '); READLN(Lib.Name); 

WRITE('Module Name: '); READLN(Module.Name); 

(♦Initialize lib for update access*) 
status := LBR$INI.CONTROL (lib_index.ptr. O 

IADDRESS(LBR$C_UPDATE), (*Update access*) 
IADDRESS(LBR$C_TYP_TXT)); (*Text library*) 

IF NOT ODD(status) THEN (*Check error status*) 

WRITELNCInitialization Failed') 

ELSE (*Initialization was successful*) 

BEGIN 

status := LBR$0PEN (lib.index.ptr, (*Open the library*) 

Lib.Name); 

IF NOT ODD(status) THEN (*Check error status*) 

WRITELNCOpen Not Successful') 

ELSE (*Open was successful*) 

BEGIN (*I8 module already in the library?*) 

status := LBR$LOOKUP_KEY (lib.index.ptr. © 

Module.Name, 
txtrfa.ptr); 

IF ODD(status) THEN (*Check status. Should not be odd*) 
WRITELN('Lookup key was successful.', 

'The module is already in the library.') 

ELSE (*Did lookup key fail because key not found?*) 

IF status = IADDRESS(LBR$_KEYNOTFND) THEN © 
Key.Not.Found := TRUE 

END 

END; 


(Continued on next page) 
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Example LBR-2 (Cont.) Inserting Module Into Library Using 

VAX PASCAL 


(******if LBR$L00KUP_KEY failed because the key was not found 
(as expected), we can open the file containing the new module, 
and write the module's records to the library file*******) 

IF Key.Not.Found THEN 
BEGIN 

OPEN(Textin,Module.Name,old); 

RESET(Textin); 

WHILE NOT EOF(Textin) DO (*Repeat until end of file*) 

BEGIN O 

READ(Textin,Text_Data_Record); (*Read record from 

external file*) 

status := LBR$PUT_RECORD (lib_index_ptr, (*Write*) 

Text_Data_Record, (*record to*) 
txtrfa.ptr); (*library*) 

IF NOT ODD(status) THEN 

WRITELN('Put Record Routine Not Successful') 

END; (*of WHILE statement*) 

IF ODD(status) THEN (*True if all the records have been 

successfully written into the library*) 

BEGIN 

status := LBR$PUT_END (lib_index_ptr); (*Write end of 

module record*) 

IF NOT ODD(status) THEN 

WRITELN('Put End Routine Not Successful') 

ELSE (*Insert key for new module*) 

BEGIN © 

status := LBR$INSERT_KEY (lib.index.ptr, 

Module_Name, 
txtrfa_ptr); 

IF NOT ODD(status) THEN 

WRITELN('Insert Key Not Successful') 

END 

END 


END; 

status := LBR$CLOSE(lib_index_ptr); 
IF NOT ODD(status) THEN 

WRITELN('Close Not Successful') 
END. (*of program insertmod*) 


© Call LBR$INI—CONTROL, specifying that the function to be performed is 
update, and the library type is text. 

© Call LBR$LOOKUP_KEY to see whether the module to be inserted is 
already in the library. 

© The call to LBR$LOOKUP_KEY should fail with the status value 
LBR$_KE YN OTFND. 

© Read a record from the input file, then use LBR$PUT_RECORD to write 
the record to the library. When all the records have been written to the 
library, use LBR$PUT_END to write an end of module record. 

© Use LBR$INSERT_KEY to insert a key for the module into the current 
index. 
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Example LBR-3 Extracting Module From Library Using VAX 
PASCAL 


PROGRAM extractmod(INPUT,OUTPUT,Textout); 

(♦This program extracts a module from a library*) 

TYPE 

Rfa.Ptr = ARRAY [0..1] OF INTEGER; (♦Data type of RFA of module*) 

VAR 


LBR$C_UPDATE, 

LBR$C_TYP_TXT, 

RMS$_EOF : [EXTERNAL] INTEGER; 

Lib.Name : VARYING [128] OF CHAR; 
Module.Name : VARYING [31] OF CHAR; 


(♦Constants for LBR$INI_C0NTR0L*) 
(♦Defined in $LBRDEF macro*) 

(*RMS return status; defined in 
$RMSDEF macro*) 

(♦Name of library receiving module*) 
(♦Name of module to insert*) 


Extracted_File : VARYING [31] OF CHAR; (*Name of file to hold 

extracted module*) 

Outtext : PACKED ARRAY [1..255] OF CHAR; (*Extracted mod put here,*) 
0uttext2 : VARYING [255] OF CHAR; (* then moved to here*) 

i : INTEGER; (*For loop control*) 

Textout : FILE OF VARYING [255] OF CHAR; (*File containing extracted 

module*) 

nullstring : CHAR; (*nullstring, pos, and len used to*) 

pos, len : INTEGER; (*find string in extracted file reed*) 

lib_index_ptr : UNSIGNED; (*Value returned in library init*) 

status : UNSIGNED; (*Return status for function calls*) 

txtrfa_ptr : Rfa.Ptr; (*For key lookup and insertion*) 

(*-*-*-*-Function Definitions-*-*-*-*) 

(♦Function that returns library 
control index used by librarian*) 

FUNCTION LBR$INI.CONTROL (VAR library.index: UNSIGNED; 

func: UNSIGNED; 
typ: UNSIGNED; 

VAR namblk: ARRAY[1..u:INTEGER] 

OF INTEGER 7.IMMED 0): 


INTEGER; EXTERN; 

(♦Function that creates/opens library*) 

FUNCTION LBR$0PEN (library.index: UNSIGNED; 

fns: [class.s]PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create.options: ARRAY [12..u2:INTEGER] OF INTEGER := 

'/.IMMED 0; 

dns: [CLASS.S] PACKED ARRAY [13..u3:INTEGER] OF CHAR 
:= %IMMED 0; 

rlfna: ARRAY [14.. u4: INTEGER] OF INTEGER := '/.IMMED 0; 
rns: [CLASS.S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
'/.IMMED 0; 

VAR rnslen: INTEGER := ‘/.IMMED 0): 

INTEGER; EXTERN; 

(♦Function that finds a key in an index*) 

FUNCTION LBRILOOKUP.KEY (library.index: UNSIGNED; 

key.name:[CLASS.S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR; 

VAR txtrfa: Rfa.Ptr): 

INTEGER; EXTERN; 

(♦Function that retrieves records from modules*) 
FUNCTION LBR$GET_RECORD (library.index: UNSIGNED; 

var textline:[CLASS.S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR): 

INTEGER; 


(Continued on next page) 
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Example LBR-3 (Cont.) Extracting Module From Library Using 

VAX PASCAL 


EXTERN; 

(♦Function that closes library*) 

FUNCTION LBR$CL0SE (library.index: UNSIGNED): 

INTEGER; EXTERN; 

BEGIN (* *************** DECLARATIONS COMPLETE ************************* 
*************** main program BEGINS HERE ********************** *) 

(* Get Library Name, Module To Extract, And File To Hold Extracted Module *) 
WRITE('Library Name: '); READLN(Lib.Name); 

WRITE('Module Name: '); READLN(Module.Name); 

WRITE('Extract Into File: '); READLN(Extracted.File); 

status := LBR$INI_CONTROL (lib.index.ptr, O 

IADDRESS(LBR$C_UPDATE), 
IADDRESS(LBR$C_TYP_TXT)); 

IF NOT ODD(status) THEN 

WRITELN('Initialization Failed') 

ELSE 

BEGIN 

status := LBR$0PEN (lib.index.ptr, 

Lib.Name); 

IF NOT ODD(status) THEN 

WRITELN('Open Not Successful') 

ELSE 

BEGIN © 

status := LBR$LOOKUP_KEY (lib.index.ptr, 

Module.Name, 
txtrfa.ptr); 

IF NOT ODD(status) THEN 

WRITELN('Lookup Key Not Successful') 

ELSE 

BEGIN @ 

OPEN(Textout,Extracted.File,new); 

REWRITE(Textout) 

END 

END 

END; 

WHILE ODD(status) DO 
BEGIN 

nullstring := ''(0); 

FOR i :* 1 TO 255 DO O 

Outtext[i] := nullstring; 
status := LBR$GET_RECORD (lib.index.ptr, 

Outtext); 

IF NOT ODD(status) THEN 

BEGIN © 

IF status = IADDRESS(RMS$_E0F) THEN 
WRITELN(' RMS end of file') 

END 


(Continued on next page) 
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Example LBR-3 (Cont.) Extracting Module From Library Using 

VAX PASCAL 


ELSE 

BEGIN © 

pos := INDEX(Outtext, nullstring); (*find first null 

in Outtext*) 

len := pos - 1; (*length of Outtext to first null*) 

IF len >= 1 THEN 
BEGIN 

0uttext2 :* SUBSTR(Outtext,1,LEN); 

WRITE(Textout.Outtext2) 

END 

END 

END; (*of WHILE*) 

status := LBR$CLOSE(lib_index_ptr); 

IF NOT ODD(status) THEN 

WRITELNCClose Not Successful') 

END. (*of program extractmod*) 

O Call LBR$INI—CONTROL, specifying that the function to be performed is 
update and the library type is text. 

© Call LBR$LOOKUP_KEY to find the key that points to the module you 
want to extract. 

© Open an output file to receive the extracted module. 

© Initialize the variable that is to receive the extracted records to null 
characters. 

© If the call to LBR$GET_RECORD fails, it should be because the end of the 
file (module) was reached. 

© The extracted record should consist only of the data up to the first null 
character. Write that data to the output file. 
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Example LBR-4 Deleting Module From Library Using VAX 
PASCAL 


PROGRAM deletemod(INPUT,OUTPUT) ; 

(♦This program deletes a module from a library*) 

TYPE 

Rfa.Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 

VAR 

LBR$C_UPDATE, (*Constants for LBR$INI.C0NTR0L*) 

LBR$C_TYP_TXT, (*Defined in $LBRDEF macro*) 

LBR$_KEYNOTFND : [EXTERNAL] INTEGER;(*Error code for LBR$L00KUP_KEY*) 
Lib.Name : VARYING [128] OF CHAR; (*Name of library receiving module*) 
Module_Name : VARYING [31] OF CHAR; (*Name of module to insert*) 
Text_Data_Record : VARYING [255] OF CHAR; (*Record in new module*) 

Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*) 
lib.index.ptr : UNSIGNED; (*Value returned in library init*) 

status : UNSIGNED; (*Return status for function calls*) 

txtrfa.ptr : Rfa.Ptr; (*For key lookup and insertion*) 

Key.Not.Found : BOOLEAN := FALSE; (*True if new mod not already in lib*) 
(*-*-*-*-Function Definitions-*-*-*-*) 

(♦Function that returns library 
control index used by librarian*) 

FUNCTION LBR$INI.CONTROL (VAR library.index: UNSIGNED; 

func: UNSIGNED; 
typ: UNSIGNED; 

VAR namblk: ARRAY[1..u:INTEGER] 

OF INTEGER := '/.IMMED 0): 

INTEGER; EXTERN; 

(♦Function that creates/opens library*) 
FUNCTION LBR$0PEN (library.index: UNSIGNED; 

fns: [class.s]PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create.options: ARRAY [12..u2:INTEGER] OF INTEGER := 

•/.IMMED 0; 

dns: [CLASS.S] PACKED ARRAY [13..u3:INTEGER] OF CHAR 
:= '/.IMMED 0; 

rlfna: ARRAY [14. . u4: INTEGER] OF INTEGER : = '/.IMMED 0; 
rns: [CLASS.S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
'/.IMMED 0; 

VAR rnslen: INTEGER := '/.IMMED 0): 

INTEGER; EXTERN; 

(♦Function that finds a key in index*) 

FUNCTION LBR$L00KUP_KEY (library.index: UNSIGNED; 

key.name:[CLASS.S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR; 

VAR txtrfa: Rfa.Ptr): 

INTEGER; EXTERN; 

(♦Function that removes a key from an index*) 
FUNCTION LBR$DELETE_KEY (library.index: UNSIGNED; 

key.name:[CLASS.S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR): 

INTEGER; 

EXTERN; 


(Continued on next page) 
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Examples of Using the LBR Routines 


Example LBR-4 (Cont.) Deleting Module From Library Using 

VAX PASCAL 


(♦Function that deletes all the records 
associated with a module*) 

FUNCTION LBR$DELETE_DATA (library.index: UNSIGNED; 

txtrfa: Rfa_Ptr): 

INTEGER; 

EXTERN; 

(♦Function that closes library*) 
FUNCTION LBR$CL0SE (library.index: UNSIGNED): 

INTEGER; EXTERN; 


BEGIN (* *************** DECLARATIONS COMPLETE ************************* 
*************** MAIN PROGRAM BEGINS HERE ********************** *) 

(♦ Get Library Name and Module to Delete *) 
WRITE('Library Name: '); READLN(Lib.Name); 

WRITE('Module Name: '); READLN(Module.Name); 

(♦Initialize lib lor update access*) 
status := LBR$INI.CONTROL (lib_index.ptr, O 

IADDRESS(LBR$C_UPDATE), (*Update access*) 
IADDRESS(LBR$C_TYP_TXT)); (*Text library*) 
IF NOT ODD(status) THEN (*Check error status*) 

WRITELNCInitialization Failed') 

ELSE (*Initialization was successful*) 

BEGIN 

status := LBR$0PEN (lib_index.ptr. (*0pen the library*) 
Lib.Name); 

IF NOT ODD(status) THEN (*Check error status*) 

WRITELNCOpen Not Successful') 

ELSE (*0pen was successful*) 

BEGIN © (*Is module in the library?*) 

status := LBRSLOOKUP.KEY (lib.index.ptr, 

Module.Name, 
txtrfa.ptr); 

IF NOT ODD(status) THEN (*Check status*) 

WRITELN('Lookup Key Not Successful') 

END 

END; 

IF ODD(status) THEN (*Key was found; delete it*) 

BEGIN 

status := LBR$DELETE_KEY (lib.index.ptr, © 

Module.Name); 

IF NOT ODD(status) THEN 

WRITELN('Delete Key Routine Not Successful') 

ELSE (*Delete key was successful*) 

BEGIN (*Now delete module's data records*) 

status := LBR$DELETE_DATA (lib.index.ptr, © 

txtrfa.ptr); 

IF NOT ODD(status) THEN 

WRITELN('Delete Data Routine Not Successful') 

END 

END; 

status := LBR$CLOSE(lib.index.ptr); (*Close the library*) 

IF NOT ODD(status) THEN 

WRITELN('Close Not Successful'); 

END. (*of program deletemod*) 


(Continued on next page) 
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Examples of Using the LBR Routines 


Example LBR-4 (Cont.) Deleting Module From Library Using 

VAX PASCAL 


O Call LBR$INI—CONTROL, specifying that the function to be performed is 
update and the library type is text. 

© Call LBR$LOOKUP—KEY to find the key associated with the module you 
want to delete. 

© Call LBR$DELETE_KEY to delete the key associated with the module you 
want to delete. If more than one key points to the module, you will have 
to call LBR$LOOKUP_KEY and LBR$DELETE —KEY for each of the keys. 

O Call LBR$DELETE_DATA to delete the module (the module header and 
data) from the library. 


8.3 LBR Routines 


The following pages describe the individual LBR routines in routine template 
format. 
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LBR$CLOSE 


LBR$CLOSE—Close a Library 



Closes an open library. 

FORMAT 

LBR$CLOSE library-index 

RETURNS 

VMS Usage: cond_value 
type: iongword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

DESCRIPTION 

When you are finished working with a library, you should call LBR$CLOSE 
to close it. Upon successful completion, LBR$CLOSE closes the open library 
and deallocates all of the memory used for processing the library. 

CONDITION 

VALUES 

RETURNED 

LBR$_ILLCTL The specified library control index is not valid. 

LBR$_LIBNOTOPN The specified library is not open. 


LBR—20 










Librarian (LBR) Routines 

LBR$DELETE_DATA 


LBR$DELETE_DATA—Delete a Module's 

Data 



Deletes the module header and data associated with the specified 
module. 

FORMAT 

LBR$DELETE_DATA library-index, txtrfa 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

txtrfa 

VMS Usage: vector—longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The record's file address (RFA) of the module header for the module you 
want to delete. The txtrfa argument is the address of a 2-longword array 
that contains the RFA. You can obtain the RFA of a module header by calling 
LBR$LOOKUP—exit KEY or LBR$PUT_RECORD. 

DESCRIPTION 

If you want to delete a library module, you must first call LBR$DELETE_KEY 
to delete any keys that point to it. If no library index keys are pointing at 
the module header, LBR$DELETE_DATA will delete the module header and 
associated data records; otherwise, this routine returns the error 

LBR$_STILLKE Y S. 

Note that other librarian routines may reuse data blocks that contain no data. 
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LBR$DELETE_DATA 


CONDITION 

VALUES 

RETURNED 


LBR$_ILLCTL 
LBR$_INVRFA 
LBR$_LIBNOT OPN 
LBR$_STILLKEYS 


The specified library control index is not valid. 
The specified RFA is not valid. 

The specified library is not open. 

Keys in other indexes still point at the module 
header; therefore, the specified module was not 
deleted. 
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LBR$DELETE_KEY 


LBR$DELETE_KEY—Delete a Key 

Deletes a key from a library index. 

FORMAT 

LBR$DELETE_KEY library-index ,key-name 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 


ARGUMENTS 


library-index 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 


key-name 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


The key to be deleted from the library index. For libraries with binary keys, 
the key-name argument is the address of an unsigned longword containing 
the key number. 

For libraries with ASCII keys, the key-name argument is the address 
of the string descriptor pointing to the key with the following argument 
characteristics. 


Argument 

Characteristics 

Entry 

VMS Usage 

Char_string 

Type 

Character string 

Access 

Read only 

Mechanism 

By descriptor 
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LBR$DELETE_KEY 


DESCRIPTION If LBR$DELETE_KEY finds the key specified by key-name in the current 


index, it deletes the key. Note that, if you want to delete a library module, 
you should first use LBR$DELETE_KEY to delete any keys that point to it, 
then use LBR$DELETE_DATA to delete the module's header and associated 
data. 

You cannot call LBR$DELETE_KEY within the user-supplied routine specified 
in LBR$SEARCH or LBR$GET_INDEX. 


CONDITION 

VALUES 

RETURNED 


LBR$_ILLCTL 


The specified library control index is not valid. 
The specified key has not been found. 

The specified library is not open. 

The specified index update is not valid in a user- 
supplied routine specified in LBRSSEARCH or 
LBR$GET_INDEX. 


LBR$_KEYNOTFND 
LBR$_LIBNOT OPN 
LBR$_UPDURTRAV 


Note: In the key-name argument, two types of situations are described. One 
description applies to libraries with ASCII keys, the other applies to 
libraries with binary keys. Only one of the key-name arguments will 
apply, depending upon the type of keys in the library. Disregard the 
key-name argument which does not apply. 
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LBR$FIND 


LBR$FIND—Lookup a Module by its RFA 



Sets the current internal read context for the specified library to the 
library module specified. 

FORMAT 

LBR$FIND library-index,txtrfa 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return (by immediate value) a 
condition value in RO. Condition values that can be returned by this routine 
are listed under "CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

txtrfa 

VMS Usage: vector—longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The RFA (record's file address) of the module header for the module you 
want to access. The txtrfa argument is the address of a 2-longword array 
that contains the RFA. You can obtain the RFA of a module header by calling 
LBR$LOOKUP_KEY or LBR$PUT_RECORD. 

DESCRIPTION 

You use the LBR$FIND routine to access a module that you had accessed 
earlier in your program. For example, if you look up several keys with 
LBR$LOOKUP_KEY, you can save the RFAs returned by LBR$LOOKUP_KEY 
and later use LBR$FIND to reaccess the modules. Thus, you do not have to 
look up the module header's key every time you want to access the module. 

If the specified RFA is valid, LBR$FIND initializes internal tables so that you 
can read the associated data. 
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LBR$FIND 


CONDITION 

LBR$_ILLCTL 

The specified 

VALUES 

LBR$_INVRFA 

The specified 

RETURNED 

LBR$_LIBNOTOPN 

The specified 


library control index is not valid. 
RFA is not valid, 
library is not open. 
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LBR$FLUSH 


LBR$FLUSH—Recover Virtual Memory 



Writes blocks that have been modified back to the library file and 
frees the virtual memory they had been using. 

FORMAT 

LBR$FLUSH library-index,block-type 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return (by immediate value) a 
condition value in RO. Condition values that can be returned by this routine 
are listed under "CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

block-type 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by value 

The extent of the flush operation. The block-type argument contains a 
longword value that indicates how the flush operation proceeds. If you 
specify LBR$C_FLUSHDATA, the data blocks will be flushed. If you specify 
LBR$C_FLUSH ALL, first the data blocks and then the current library index 
will be flushed. 

The LBR$ symbols LBR$C_FLUSHDATA and LBR$C_FLUSHALL are defined 
in the macro $LBRDEF (found in SYS$LIBRARY:STARLET.MLB), which must 
be assembled and then linked with your program. 

DESCRIPTION 

LBR$FLUSH cannot be called from other librarian routines that reference 
cache addresses, or by routines called by librarian routines. 
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LBR$FLUSH 


CONDITION 

VALUES 

RETURNED 


LBR$_NORMAL 

LBR$_BADPARAM 

LBR$_WRITERR 


The operation completed successfully. 

A value passed to the LBRSFLUSH routine was 
either out of range or an illegal value. 

An error occurred during the writing of the cached 
update blocks to the library file. 
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LBR$GET_HEADER 


LBR$GET_HEADER—Retrieve Library 

Header Information 

Returns information from the library's header to the caller. 


FORMAT LBR$GET_HEADER library-index ,retary 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. All utility routines return (by immediate value) a 
condition value in RO. Condition values that can be returned by this routine 
are listed under "CONDITION VALUES RETURNED." 


ARGUMENTS 


library-index 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


The library control index which was returned by the LBR$INI_CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 


retary 

VMS Usage: 
type: 
access: 
mechanism: 


vector_longword—signed 
longword (signed) 
write only 
by reference 


An array of 128 longwords that receives the library header. The retary 
argument is the address of the array that contains the header information. 
The information returned in the array follows (the symbols are defined by the 
$LHIDEF macro in SYS$LIBRARY:STARLET.MLB.). 


Offset in 
Longwords 

Symbolic Name 

Contents 

0 

LHI$I_TYPE 

Library type; see LBRSOPEN for possible 
values 

1 

LHI$L_NINDEX 

Number of indexes 

2 

LHI$L_MAJORID 

Library format major identification 

3 

LHI$L_MINORID 

Library format minor identification 

4 

LHI$T_LBRVER 

ASCIC version of Librarian 

12 

LHI$L _CRED AT 

Creation date/time 
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LBR$GET_HEADER 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


Offset in 

Longwords Symbolic Name Contents 


14 

LHI$I_UPDTIM 

16 

LHI$I_UPDHIS 

17 

LHI$I_FREEVBN 

18 

LHlSl_FREEBLK 

19 

LHI$B_NEXTRFA 

21 

LHI$I_NEXTVBN 

22 

LHI$I_FREIDXBLK 

23 

LHI$I_FREEIDX 

24 

LHI$I_HIPREAL 

25 

LHI$L_IDXBLKS 

26 

LHI$I_IDXCNT 

27 

LHISL _MODCNT 

28 

LHI$L _MHDUSZ 

29 

LHI$L_MAXLUHREC 

30 

LHlSl_NUMLUHREC 

31 

LHI$I_LIBST ATUS 

32-128 



Date/time of last update 
VBN of start of update history 
First logically deleted block 
Number of deleted blocks 

Record's File Address (RFA) of end of 
library 

Next VBN to allocate at end of file 
Number of free preallocated index blocks 
Listhead for preallocated index blocks 
VBN of highest preallocated block 
Number of index blocks in use 
Number of index entries (total) 

Number of entries in index 1 (module 
names) 

Number of bytes of additional information 
reserved in module header 

Maximum number of library update 
history records maintained 

Number of library update history records 
in history 

Library status (false if there was an error 
closing the library) 

Reserved to DIGITAL 


On successful completion, LBR$GET_HEADER places the library header 
information into the array of 128 longwords. 

Note that the offset is the byte offset of the value into the header structure. 
You can convert the offset to a longword subscript by dividing the offset by 4 
and adding 1 (assuming that subscripts in your programming language begin 
with 1). 


LBR$_LIBNOT OPN 
LBR$_ILLCTL 


The specified library is not open. 

The specified library control index is not valid. 
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LBR$GET_HELP 


LBR$GET_ 

.HELP—Retrieve Help Text 

Retrieves help text from a help library, displaying it on 
SYS$OUTPUT or calling your routine for each record returned. 

Note that most application programs will use LBR$OUTPUT_HELP 
instead of LBR$GET_HELP. 

FORMAT 

LBR$GET_HELP library-index[,line-width][,routine] 

[,data][,key-1][,key-2... ,key-10] 

If the key-1 descriptor is 0, or if it is not present, LBR$GET_HELP will 
assume that the key-1 name is "HELP," and it ignores all the other keys. For 
key-2 through key-10, a descriptor address of 0, or a length of 0, or a string 
address of 0 will terminate the list. 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return (by immediate value) a 
condition value in R0. Condition values that can be returned by this routine 
are listed under "CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

line-width 

VMS Usage: longword—signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

The width of the help text line. The line-width argument is the address of 
a longword that contains the width of the listing line. If you do not supply 
a line-width or if you specify 0, the line-width defaults to 80 characters per 
line. 
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LBR$GET_HELP 


routine 

VMS Usage: 
type: 
access: 
mechanism: 


procedure 

procedure entry mask 
read only 
by reference 


Routine called for each line of text you want output. The routine argument is 
the address of the entry mask for this user written routine. 


If you do not supply a routine argument, LBR$GET_HELP calls the 
Run-Time Library procedure LIB$PUT_OUTPUT to send the help text 
lines to the current output device (SYS$OUTPUT). However, if you want 
SYS$OUTPUT for your program to be a disk file, rather than the terminal, it 
is recommended that you supply a routine to output the text. 


The routine that you specify will be called with an argument list of four 
longwords: 


1 The first argument is the address of a string descriptor for the line to be 
output. 

2 The second argument is the address of an unsigned longword containing 
flag bits which describe the contents of the text being passed. The possible 
flags are: 

HLP$M_NOHLPTXT - The specified help text cannot be found. 

HLP$M_KEYNAMLIN - The text contains the key names of the printed 

text. 

HLP$M_OTHERINFO - The text is part of the information provided on 

additional help available. 

(The $HLPDEF macro in SYS$LIBRARY:STARLET.MLB defines these flag 
symbols.) 

Note that, if no flag bit is set, help text is being passed. 

3 The third argument is the address specified in the data argument specified 
in the call to LBR$GET_HELP (or the address of a 0 constant if the data 
argument is zero or was omitted). 

4 The fourth argument is a longword containing the current key level. 


The routine that you specify must return with success or failure status. A 
failure status (low bit = 0) terminates the current call to LBR$GET_HELP. 


data 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Data passed to the routine specified in the routine argument. The data 
argument is the address of data for the routine. The address will be passed 
to the routine specified in the routine argument. If you omit this argument 
or specify it as zero, then the argument passed in your routine will be the 
address of a zero constant. 
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LBR$GET_HELP 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


key-1,key-2,...,key-10 


VMS Usage: 
type: 
access: 
mechanism: 


longword—signed 
longword (signed) 
read only 
by descriptor 


The level of the help text to be output. Each key-l,key-2,...,key-10 argument 
is the address of a descriptor pointing to the key for that level. 

If the key-1 descriptor is 0 or if it is not present, LBR$GET_HELP will assume 
that the key-1 name is "HELP", and it ignores all the other keys. For key-2 
through key-10, a descriptor address of 0, or a length of 0, or a string address 
of 0 will terminate the list. 


The key argument may contain any of the following special character strings: 


String Meaning 

* Return all level 1 help text in the library 

KEY... Return all help text associated with the specified key and its subkeys 
(valid for level 1 keys only) 

*... Return all help text in the library 


LBR$GET_HELP returns all help text in the same format as the output 
returned by the DCL command HELP; that is, it indents two spaces for every 
key level of text displayed. (Note that, because of this formatting, you may 
want to make your help messages shorter than 80 characters, so they fit on 
one line on terminal screens with the width set to 80.) If you do not want the 
help text indented to the appropriate help level, you must supply your own 
routine to change the format. 


LBRS—ILLCTL 

LBR$_LIBNOTOPN 

LBR$_NOTHLPLIB 


The specified 
The specified 
The specified 


library control index is not valid. 

library is not open. 

library is not a help library. 
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LBR$GET_HISTORY 


LBR$GET_ 

-HISTORY—Retrieve a Library 

Update History 
Record 

Returns each library update history record to a user-specified action 
routine. 

FORMAT 

LBR$GET_HISTORY library-index,action-routine 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return (by immediate value) a 
condition value in RO. Condition values that can be returned by this routine 
are listed under "CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI_CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

action-routine 

VMS Usage: procedure 
type: procedure entry mask 

access: modify 

mechanism: by reference 

A user-supplied routine for processing library update history records. The 
action-routine argument is the address of the entry mask of this user- 
supplied routine. The routine is invoked once for each update history record 
in the library. One argument is passed to the routine: the address of a 
descriptor pointing to a history record. 


DESCRIPTION This routine retrieves the library update history records which were written 

by the routine LBR$PUT_HISTORY. 
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LBR$GET_HISTORY 


CONDITION 

VALUES 

RETURNED 


LBR$_NORMAL 

LBR$_EMPTYHIST 

LBR$_NOHISTORY 

LBR$_INTRNLERR 


A normal exit from the routine occurred. 

The history is empty. This is an informational 
code, not an error code 

This library does not have an update history. This 
is an informational code, not an error code 

An internal librarian routine error occurred. 
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LBR$GET_INDEX 


LBR$GET_ 

.INDEX—Call a Routine for 

Selected Index Keys 

Calls a user-supplied routine for selected keys in an index. 

FORMAT 

LBR$GET_INDEX library-index,index-number 

,routine-name [,match-desc] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return (by immediate value) a 
condition value in RO. Condition values that can be returned by this routine 
are listed under "CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

index-number 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Number of the library index. The index-number argument is the address of a 
longword containing the index number. This is the index number associated 
with the keys you want to use as input to the user-supplied routine (see 
Section 8.1.2.3). 

routine-name 

VMS Usage: procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

Routine called for each of the specified index keys. The routine-name 
argument is the address of the entry mask for this user-supplied routine. 
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LBR$GET_INDEX 


LBR$GET_INDEX passes two arguments to the routine: 

1 A key-name. 

• For libraries with ASCII keys, the key-name argument is the address 
of a string descriptor pointing to the key. Note that the string and the 
string descriptor passed to the routine are valid only for the duration of 
that call. The string must be privately copied if you need it again for 
more processing. 

• For libraries with binary keys, the key-name argument is the address 
of an unsigned longword containing the key number. 

2 The record's file address (RFA) of the module's header for this key-name. 

The RFA argument is the address of a 2-longword array that contains the 

RFA. 

The routine must return a value to indicate success or failure. If the routine 
returns a false value (low bit = 0), LBR$GET_INDEX stops searching the 
index and returns the status value of the user-specified routine to the calling 
program. 

The routine cannot contain calls to either LBR$DELETE_KEY or 
LBR$INSERT_KEY. 


match-desc 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


The key matching identifier. The match-desc argument is the address of a 
string descriptor pointing to a string which is used to identify which keys will 
result in calls to the user-supplied routine. Wildcard characters are allowed 
in this string. If this argument is omitted, the routine is called for every key 
in the index. The match-desc argument is valid only for libraries that have 
ASCII keys. 


DESCRIPTION LBR$GET_INDEX searches through the specified index for a key that matches 

the argument match-desc. Each time it finds a match, it calls the routine 
specified by the routine-name argument. If the match-desc argument is not 
specified, it calls the routine for every key in the index. 

For example, if you call LBR$GET_INDEX with match-desc equal to TR* and 
index-number set to 1 (module name table), then LBR$GET_INDEX will call 
routine-name for each module whose name begins with TR. 


CONDITION 

LBR$_ILLCTL 

The specified 

VALUES 

LBR$_ILLIDXNUM 

The specified 

RETURNED 

LBR$_LIBNOTOPN 

The specified 


LBR$_NULIDX 

The specified 


library control index is not valid, 
index number is not valid, 
library is not open, 
library is empty. 
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LBR$GET_ 

.RECORD—Read a Data Record 

Returns the next data record in the module associated with a 
specified key. 

FORMAT 

LBR$GET_RECORD library-index[Jnbufdes] 

[ r outbufdes] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return (by immediate value) a 
condition value in RO. Condition values that can be returned by this routine 
are listed under "CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. The library must be open and LBR$LOOKUP_KEY or 
LBR$FIND must have been called to find the key associated with the module 
whose records you want to read. 

inbufdes 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

A user buffer to receive the record. The inbufdes argument is the address of 
a string descriptor that points to the buffer that will receive the record from 
LBR$GET_RECORD. This argument is required when the librarian subroutine 
record access is set to move mode (which is the default). This argument is not 
used if the record access mode is set to locate mode. The Description section 
below contains a description of the locate and move modes. 

outbufdes 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

A string descriptor that receives the actual length and address of the data 
for the record returned. The outbufdes argument is the address of the string 
descriptor for the returned record. The length and address fields of the string 
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descriptor are filled in by the LBR$GET__RECORD routine. This parameter 
must be specified when Librarian subroutine record access is set to locate 
mode. This parameter is optional if record access mode is set to move mode. 
The Description section below contains a description of the locate and move 
modes. 

DESCRIPTION 

Before calling LBR$GET_RECORD, you must first call LBR$LOOKUP_KEY, or 
LBR$FIND, to set the internal library read context to the record's file address 
(RFA) of the module header of the module whose records you want to read. 

LBR$GET_RECORD uses two record access modes: locate mode and move 
mode. Move mode is the default. The LBR$SET_LOCATE and 
LBR$SET_MOVE subroutines set these modes. The record access modes 
are mutually exclusive, that is, when one is set the other is turned off. If 
move mode is set, LBR$GET_RECORD copies the record to the user-specified 
buffer described by inbufdes. If you have optionally specified the output 
buffer string descriptor, outbufdes, the librarian fills it with the actual length 
and address of the data. If locate mode is set, LBR$GET_RECORD returns 
the record by way of an internal subroutine buffer, pointing the outbufdes 
descriptor to the internal buffer. The second parameter, inbufdes, is not used 
when locate mode is set. 

CONDITION 

VALUES 

RETURNED 

LBR$_ILLCTL The specified library control index is not valid. 

LBR$_LIBNOTOPN The specified library is not open. 

LBR$_LKPNOTDON The requested key lookup has not been done. 

RMS$_EOF An attempt has been made to read past the logical 

end of the data in the module. 
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LBR$IIMI_COI\ITROL—Initialize a Library 

Control Structure 

Initializes a control structure, called a library control index, to identify 
the library for use by other Librarian routines. You may have up to 
16 libraries open simultaneously in your program. 


FORMAT LBR$INI_CONTROL library-index,func[,type] 

[,namblk] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 


"CONDITION VALUES RETURNED." 


ARGUMENTS 


library-index 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


The library control index returned by the LBR$INI_CONTROL routine. The 
library-index argument is the address of a longword that will receive the 
index. 


func 

VMS Usage: 
type: 
access: 
mechanism: 


function _code 
longword (unsigned) 
read only 
by reference 


The library function to be performed. The func argument is the address of a 
longword that contains the library function. Valid functions are 
LBR$C_CREATE, LBR$C_READ, and LBR$C_UPDATE. (These symbols are 
defined by the $LBRDEF macro in SYS$LIBRARY:STARLET.MLB.) 


type 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


The library type. The type argument is the address of a longword that 
contains the library type. Valid library types are: LBR$C_TYP_OBJ (object 
or shareable image), LBR$C_TYP_MLB (macro), LBR$C_TYP_HLP (help), 
LBR$C_TYP_TXT (text), LBR$C_TYP_UNK (unknown), or, for 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


user_developed libraries, a type in the range of LBR$C_TYP_USRLW 
through LBR$C_TYP_USRHI. 


namblk 

VMS Usage: 
type: 
access: 
mechanism: 


nam 

longword (unsigned) 
read only 
by reference 


A VAX Record Management Services (VAX RMS) name (NAM) block. The 
namblk argument is the address of a variable length data structure containing 
an RMS NAM block. The LBR$OPEN routine fills in the information in the 
NAM block so that it can be used later to open the library. If the NAM block 
has this file identification in it from previous use, the LBR$OPEN routine will 
use the VAX RMS open-by-NAM block option. This argument is optional and 
should be used if the library will be opened many times during a single run 
of the program. For a detailed description of VAX RMS NAM blocks, see the 
VAX Record Management Services Reference Manual. 


Except for the LBR$OUTPUT_HELP routine, you must call 
LBR$INI—CONTROL before calling any other librarian routine. After you 
initialize the library control index, you must open the library or create a new 
one using the LBR$OPEN routine. You can then call other librarian routines 
that you need. Once you have completed working with a library, close it with 
the LBR$CLOSE routine. 

LBR$INI_CONTROL initializes a library by filling the longword referenced 
by the library-index argument with the control index of the library. Upon 
completion of the call, the index can be used to refer to the current library in 
all future routine calls. Therefore, your program must not alter this value. 


LBR$_NORMAL 

LBR$_ILLFUNC 

LBR$_ILLTYP 

LBR$_TOOMNYLIB 


The library control index was initialized 
successfully. 

The requested function is not valid. 

The specified library type is not valid. 

An attempt was made to allocate more than 16 
control indexes. 
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LBR$INSERT_KEY—Insert a New Key 

Inserts a new key in the current library index. 

FORMAT 

LBR$INSERT_KEY library-index,key-name ,txtrfa 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 


ARGUMENTS 


library-index 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 


key-name 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


The name of the new key you are inserting. 

If the library uses binary keys, the key-name argument is the address of an 
unsigned longword containing the value of the key. 

If the library uses ASCII keys, the key-name argument is the address of a 
string descriptor of the key with the following argument characteristics. 


Argument 

Characteristics 

Entry 

VMS Usage 

Char_string 

Type 

Character string 

Access 

Write only 

Mechanism 

By descriptor 
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txtrfa 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

The record's file address (RFA) of the module associated with the new key 
you are inserting. The txtrfa argument is the address of a 2-longword array 
that contains the RFA. You can use the RFA returned by the first call to 
LBR$PUT_RECORD. 

DESCRIPTION 

You cannot call LBR$ INSERT-KEY within the user-supplied routine specified 
in LBR$SEARCH or LBR$GET_INDEX. 

CONDITION 

VALUES 

RETURNED 

LBR$_ILLCTL The specified library control index is not valid. 

LBR$_INVRFA The specified RFA does not point to valid data. 

LBR$_DUPKEY The index already contains the specified key. 

LBR$_LIBNOTOPN The specified library is not open. 

LBR$_UPDURTRAV LBR$INSERT_KEY was called by the user-defined 

routine specified in LBR$SEARCH or 
LBR$GET_INDEX. 


Note: In the key-name argument, only one of the two definitions will apply. 
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LBR$LOOKUP_KEY—Look Up a Library 

Key 



Looks up a key in the library’s current index, and prepares to access 
the data in the module associated with the key. 

FORMAT 

LBR$LOOKUP_KEY library-index,key-name, txtrfa 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

key-name 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The name of the library key. If the library uses binary keys, the key-name 
argument is the address of the unsigned longword value of the key. 

If the library uses ASCII keys, the key-name argument is the address of a 
string descriptor for the key. 

Argument 

Characteristics Entry 

VMS Usage Char_string 

Type Character string 

Access Read only 

Mechanism By descriptor 
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txtrfa 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

The record's file address (RFA) of the library module header. The txtrfa 
argument is the address of a 2-longword array that receives the RFA of the 
module header. 

DESCRIPTION 

If LBR$LOOKUP_KEY finds the specified key, it initializes internal tables so 
that you can access the associated data. 

This routine returns the RFA (consisting of the virtual block number (VBN) 
and the byte offset) to the 2-longword array referenced by txtrfa. Note that 
the RFA is only 6 bytes long. 

CONDITION 

VALUES 

RETURNED 

LBR$_JLLCTL The specified library control index is not valid. 

LBR$_INVRFA The RFA obtained is not valid. 

LBR$_KEYNOTFND The specified key was not found. 

LBR$_LIBNOTOPN The specified library is not open. 


Note: In the key-name argument, only one of the two descriptions applies, 
depending upon whether the library has ASCII keys or binary keys. 
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LBR$OPEIM—Open or Create a Library 



Opens an existing library or creates a new one. 

FORMAT 

LBR$OPEN library-index [, fns] [, create-options] [,dns] 
[, rlfna] [,rns] [, rnslen] 

The fns argument and the create-options argument are required in some 
circumstances. See the descriptions of these arguments for more information. 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI_CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

fns 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by descriptor 

The file specification of the library. The fns argument is the address of a 
string descriptor that points to the file specification. Unless the VAX RMS 
NAM block address was previously supplied in the LBR$INI—CONTROL 
routine and it contained a file specification, this argument must be included. 
Otherwise, the librarian returns an error (LBR$_NOFILNAM). 

create-options 

VMS Usage: vector—longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library characteristics. The create-options argument is the address 
of an array of 20 longwords that define the characteristics of the library 
you are creating. If you are creating a library with LBR$C_CREATE, you 
must include the create-options argument. The following table shows the 
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entries that the array must contain (the $LBRDEF and $CREDEF macros in 
SYS$LIBRARY:STARLET.MLB define the symbols listed): 


Offset in 
Longwords 

Symbolic Name 

Contents 

0 

CRE$L_TYPE 

Library type: 


LBR$C_TYP_UNK(0) 

Unknown/unspecified 


LBR$C_TYP_OBJ (1) 

Object and/or shareable image 


LBR$C_TYP_MLB (2) 

Macro 


LBR$C_TYP_HLP(3) 

Help 


LBR$C_TYP_TXT (4) 

Text 


(5-127) 

Reserved to DIGITAL 


LBR$C_TYP_USR (128-255) 

User-defined 

1 

CRESI_KEYLEN 

Maximum length of ASCII 
keys or, if 0, indicates 32-bit 
unsigned keys (binary keys) 

2 

CRE$L _ALL0C 

Initial library file allocation 

3 

CRESI_IDXMAX 

Number of library indexes 
(maximum of 8) 

4 

CRESI_UHDMAX 

Number of additional bytes to 
reserve in module header 

5 

CRESL-ENTALL 

Number of index entries to 
preallocate 

6 

CRESI_LUHMAX 

Maximum number of library 
update history records to 
maintain 

7 

CRESL—VERTYP 

Format of library to create: 


CRE$C_VMSV2 

VAX/VMS Version 2.0 


CRE$C_VMSV3 

VAX/VMS Version 3.0 

8 

CRESL-IDXOPT 

Index key casing option: 


CRESC—HLPCASING 

Treat character case as it is for 
help libraries 


CRESC-OBJCASING 

Treat character case as it is for 
object libraries 


CRESC—M ACTXTC AS 

Treat character case as it is for 
macro and text libraries 

9-20 


Reserved to DIGITAL 


The input of uppercase and lowercase characters is treated differently for 
help, object, macro, and text libraries. For details, see the VAX/VMS Librarian 
Reference Manual. 
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dns 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


The default file specification. The dns argument is the address of a string 
descriptor that points to the default file specification. See the VAX Record 
Management Services Reference Manual for details about how defaults are 
processed. 


rlfna 

VMS Usage: 
type: 
access: 
mechanism: 


longword_unsigned 
longword (unsigned) 
read only 
by reference 


The related file name. The rlfna argument is the address of a VAX RMS 
NAM block pointing to the related file name. If you do not specify rlfna, no 
related file name processing occurs. If a related file name is specified, only 
the file name, type, and version fields of the NAM block are used for related 
name block processing. The device and directory fields are not used. See the 
VAX Record Management Services Reference Manual for details on processing 
related file names. 


rns 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
write only 
by descriptor 


The resultant file specification returned. The rns argument is the address of a 
string descriptor pointing to a buffer to receive the resultant file specification 
string. If an error occurs during an attempt to open the library, the expanded 
name string will be returned instead. 


rnslen 

VMS Usage: 
type: 
access: 
mechanism: 


longword—signed 
longword (signed) 
write only 
by reference 


The length of the resultant or expanded file name. The rnslen argument 
is the address of a longword that receives the length of the resultant file 
specification string (or the length of the expanded name string if there was an 
error in opening the library). 


DESCRIPTION This routine must be called after you call LBR$INI—CONTROL and before 

you call any other Librarian routine except LBR$OUTPUT-HELP. 

When the library is successfully opened, the Librarian reads the library header 
into memory and sets the default index to 1. 

If the library cannot be opened because it is already open for a write 
operation, LBR$OPEN will retry the open operation every second for a 
maximum of 30 seconds before returning the VAX RMS error, RMS$_FLK, to 
the caller. 
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CONDITION 

VALUES 

RETURNED 


LBR$_OLDLIBRARY 

LBR$_ERRCLOSE 


LBR$_ILLCREOPT 

LBR$_ILLCTL 

LBRS—ILLFMT 

LBR$_ILLFUNC 

LBR$_LIBOPN 

LBR$_NOFILNAM 

LBR$_OLDMISMCH 

LBR$_TYPMISMCH 


The specified library has been opened; the library 
was created with an old library format. This is a 
success code. 

When the library was last modified while opened 
for write access, the write operation was 
interrupted. This left the library in an inconsistent 
state. 

The requested create options are not valid or not 
supplied. 

The specified library control index is not valid. 

The specified library format is not valid. 

The specified library function is not valid. 

The specified library is already open. 

The fns argument was not supplied or the VAX 
RMS NAM block was not filled in. 

The requested library function conflicts with the 
old library type specified. 

The library type does not match the requested 
type. 
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LBR$OUTPUT_HELP—Output Help 

Messages 



Outputs help text to a user-supplied output routine. The text is 
obtained from an explicitly named help library, or optionally, from 
user-specified default help libraries. An optional prompting mode 
is available that enables LBR$OUTPUT_HELP to interact with a user 
and continue to provide help information after the initial help request 
has been satisfied. 

FORMAT 

LBR$OUTPUT_HELP output-routine [,output-width] 

[Jine-desc] [,library-name] 

[, flags] [,input-routine] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return (by immediate value) a 
condition value in RO. Condition values that can be returned by this routine 
are listed under "CONDITION VALUES RETURNED." 

ARGUMENTS 

output-routine 

VMS Usage: procedure 
type: procedure entry mask 

access: write only 

mechanism: by reference 

The name of a routine that writes help text a line at a time. The output- 
routine argument is the address of the entry mask of the routine to call. You 
should specify either the address of LIB$PUT_OUTPUT or a routine of your 
own that has the same calling format as LIB$PUT_OUTPUT. 

output-width 

VMS Usage: longword_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

The width of the help text line. The output-width argument is the address 
of a longword that contains the width of the text line to be passed to the 
user-supplied output routine. If output-width is omitted or 0, the default 
output-width is 80 characters per line. 
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line-desc 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


The contents of the help request line. The line-desc argument is the address 
of a string descriptor pointing to a character string containing one or more 
help keys defining the help requested, for example, the HELP command line 
minus the HELP command and HELP command qualifiers. The default is a 
string descriptor for an empty string. 


library-name 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


The name of the main library. The library-name argument is the address of 
a string descriptor pointing to the main library file specification string. The 
default is a null string, which means use the default help libraries. If the 
device and directory specifications are omitted, the default is SYS$HELP. The 
default file type is HLB. 


flags 

VMS Usage: 
type: 
access: 
mechanism: 


mask-Jongword 
longword (unsigned) 
read only 
by reference 


Flags specifying help output options. The flags argument is the address of an 
unsigned longword that contains the following flags: 


Flag 

Description 

HLP$M_PROMPT 

When set, interactive help prompting is in effect. 

HLP$M_PROCESS 

When set, the process logical name table is searched for 
default help libraries. 

HLP$M_GROUP 

When set, the group logical name table is searched for 
group default help libraries. 

HLP$M_SYSTEM 

When set, the system logical name table is searched for 
system default help libraries. 

HLP$M_LIBLIST 

When set, the list of default libraries available is output 
with the list of topics available. 

HLP$M_HELP 

When set, the list of topics available in a help library is 
preceded by the major portion of the text on HELP. 


(The $HLPDEF macro in SYS$LIBRARY:STARLET.MLB defines these flag 
symbols.) 

If this longword is omitted, the default is for prompting and all default library 
searching to be enabled, but no library list will be generated and no help text 
will precede the list of topics. 
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input-routine 


VMS Usage: 
type: 
access: 
mechanism: 


procedure 

procedure entry mask 
read only 
by reference 


Routine used for prompting. The input-routine argument is the address 
of the entry mask of the prompting routine. You should specify either the 
address of LIB$GET_INPUT or a routine of your own that has the same 
calling format as LIB$GET_INPUT. This argument must be supplied when 
the HELP command is run in prompting mode (that is, HLP$M_PROMPT is 
set or defaulted). 


DESCRIPTION LBR$OUTPUT_HELP routine provides a simple, one-call method to initiate 

an interactive help session. Help library bookkeeping functions, such as 
LBR$INI_CONTROL and LBR$OPEN, are handled internally. You should 
not call LBR$INI_CONTROL or LBR$OPEN before you issue a call to 
LBR$OUTPUT_HELP. 

LBR$OUTPUT_HELP accepts help keys in the same format as 
LBR$GET_HELP, with the following qualifications: 

1 If the keyword HELP is supplied, help text on HELP is output, followed 
by a list of HELP subtopics available. 

If no help keys are provided or if the line-desc argument is 0, a list of 
topics available in the root library is output. 

2 If the line-desc argument contains a list of help keys, then each key must 
be separated from its predecessor by a slash (/) or by one or more spaces. 

3 The first key can specify a library to replace the main library as the root 
library (the first library searched) in which LBR$OUTPUT_HELP searches 
for help. A key used for this purpose must have the form <@filespec>, 
where filespec is subject to the same restrictions as the library-name 
argument. If the specified library is an enabled user-defined default 
library, then filespec can be abbreviated as any unique substring of that 
default library's logical name translation. 

In default library searches, you can define one or more default libraries for 
LBR$OUTPUT_HELP to search for help information not contained in the 
root library. You do this by equating the logical names HLP$LIBRARY, 
HLP$LIBRARY_1,...,HLP$LIBRARY_999 to the file specifications of the 
default help libraries. These logical names can be defined in the process, 
group, or system logical name tables. 

If default library searching is enabled by the flags argument, 
LBR$OUTPUT_HELP uses those flags to determine which logical name tables 
are enabled, and then automatically searches any user default libraries that 
have been defined in those logical name tables. The library search order 
proceeds as follows: root library, main library (if specified and different from 
the root library), process libraries (if enabled), group libraries (if enabled), 
system libraries (if enabled). If the requested help information is not found 
in any of these libraries, LBR$OUTPUT_HELP returns to the root library and 
issues a help not found message. 

To enter an interactive help session (after your initial request for help has 
been satisfied) you must set the HLP$M_PROMPT bit in the flags argument. 


LBR—52 






Librarian (LBR) Routines 

LBR$OUTPUT_HELP 


You can encounter four different types of prompts in an interactive help 
session. Each type represents a different level in the hierarchy of help 
available to you: 

1 If the root library is the main library and you are not currently examining 
help for a particular topic, the prompt "Topic?" is output. 

2 If the root library is a library other than the main library and if you are 
not currently examining help for a particular topic, a prompt of the form 

<library-spec> Topic?" is output. 

3 If you are currently examining help for a particular topic (and subtopics), a 
prompt of the form " < key word... > subtopic?" is output. 

4 A combination of 2 and 3. 

When you encounter one of these prompt messages, you can respond in any 
one of several ways. Each type of response, and its effect on 
LBR$OUTPUT_HELP in each prompting situation, are described below: 


Response 

Action in the Current Prompt Environment 1 

keyword [...] 

(1,2) Search all enabled libraries for these keys. 

(3,4) Search additional help for the current topic 
(and subtopic) for these keys. 

@filespec [keyword[...]] 

(1,2) Same as above, except that the root library 
is the library specified by filespec. If the specified 
library does not exist, treat @filespec as a normal 
key. 

(3,4) Same as above; treat @filespec as a normal 
key. 

? 

(1,2) Display a list of topics available in the root 
library. 

(3,4) Display a list of subtopics of the current 
topic (and subtopics) for which help exists. 

Carriage Return 

(1 ) Exit from LBR$OUTPUT_HELP. 

(2) Change root library to main library. 

(3,4) Strip the last keyword from a list of 
keys defining the current topic (and subtopic) 
environment. 

CTRL/Z 

(1,2,3,4) Exit from LBR$OUTPUT_HELP. 

1 Keyed to the prompt in the preceding list. 
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LBR$OUTPUT_HELP 


CONDITION 

VALUES 

RETURNED 


LBR$_ILLINROU 

LBR$_ILLOUTROU 

LBR$_NOHLPLIS 
LBR$_T OOMN Y ARG 
LBR$_USRINPERR 


The input routine was improperly specified or 
omitted. 

The output routine was improperly specified or 
omitted. 

No default help libraries can be opened. 

Too many arguments were specified. 

An error status was returned by the user-supplied 
input routine. 
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LBR$PUT_ 

.END—Write an End-of-Module 
Record 

Marks the end of a sequence of records written to a library by the 
LBR$PUT_RECORD routine. 

FORMAT 

LBR$PUT_END library-index 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

library-index 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI_CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

DESCRIPTION 

Call LBR$PUT_END after you have written data records to the library with 
the LBR$PUT_RECORD routine. LBR$PUT_END terminates a module by 
attaching a 3-byte logical end-of-file record (hexadecimal 77,00,77) to the 
data. 

CONDITION 

VALUES 

RETURNED 

LBR$_ILLCTL The specified library control index is not valid. 

LBR$_LIBNOTOPN The specified library is not open. 
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LBR$PUT_ 

.HISTORY—Write an Update 

History Record 

Adds an update history record to the end of the update history list. 

FORMAT 

LBR$PUT_HISTORY library-index ,record-desc 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

record-desc 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The library history record. The record-desc argument is the address of a 
string descriptor pointing to the record to be added to the library update 
history. 

DESCRIPTION 

LBR$PUT_HISTORY writes a new update history record. If the library 
already contains the maximum number of history records (as specified at 
creation time by CRE$L _LUHMAX, see LBR$OPEN for details), the oldest 
history record is deleted before the new record is added. 
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CONDITION 

VALUES 

RETURNED 


LBR$_NORMAL 
LBR$_NOHIST ORY 

LBRS—INTRNLERR 

LBR$_RECLNG 


A normal exit from the routine occurred. 

This library does not have an update history. This 
is an informational code, not an error code 

An internal Librarian error occurred. 

The record length was greater than that specified 
by LBR$C_MAXRECSIZ. The record was not 
inserted or truncated. 
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LBR$PUT_ 

-RECORD—Write a Data Record 

Writes a data record beginning at the next free location in the library. 

FORMAT 

LBR$PUT_RECORD library-index ,bufdes , txtrfa 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI_CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

bufdes 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The record to be written to the library. The bufdes argument is the address 
of a string descriptor that points to the buffer containing the output record. 

txtrfa 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by descriptor 

The record's file address (RFA) of the module header. The txtrfa argument is 
the address of a 2-longword array that receives the RFA of the newly created 
module header upon the first call to LBR$PUT__RECORD. 
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DESCRIPTION 

If this is the first call to LBR$PUT_RECORD, this routine first writes a module 
header and returns its RFA to the 2-longword array pointed to by txtrfa. 
LBR$PUT_RECORD then writes the supplied data record to the library. 

On subsequent calls to LBR$PUT_RECORD, this routine writes the data 
record beginning at the next free location in the library (after the previous 
record). The last record written for the module should be followed by a call 
to LBR$PUT_END. 

CONDITION 

VALUES 

RETURNED 

LBR$_ILLCTL The specified library control index is not valid. 

LBR$_LIBNOTOPN The specified library is not open. 
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LBR$R EPLACE _KEY—Replace a Library 

Key 



Inserts a key in an index by changing the pointer associated with an 
existing key, or by inserting a new key. 

FORMAT 

LBR$REPI_ACE_KEY library-index ,key-name,oldrfa 

,newrfa 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

key-name 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The library key. The key-name argument is the address of a string descriptor 
for the key (for libraries with ASCII keys). 

key-name 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library key. The key-name argument is the address of an unsigned 
longword value for the key (for libraries with binary keys). 
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oldrfa 

VMS Usage: 
type: 
access: 
mechanism: 


vector_longword_unsigned 
longword (unsigned) 
write only 
by reference 


The old RFA. The oldrfa argument is the address of a 2-longword array that 
contains the original RFA (returned by LBR$LOOKUP__KEY) of the module 
header associated with the key you are replacing. 


newrfa 

VMS Usage: 
type: 
access: 
mechanism: 


vector_longword_unsigned 
longword (unsigned) 
read only 
by reference 


The new RFA. The newrfa argument is the address of a 2-longword array 
that contains the RFA (returned by LBR$PUT_RECORD) of the module 
header associated with the new key. 


DESCRIPTION If LBR$REPLACE _KEY does not find the key in the current index, it calls the 
LBR$INSERT—KEY routine to insert the key. If LBR$REPLACE —KEY does 
find the key, it modifies the key entry in the index so that it points to the new 
module header. 


CONDITION 

LBR$_ILLCTL 

The specified 

VALUES 

LBR$_LIBNOTOPN 

The specified 

RETURNED 

LBR$_INVRFA 

The specified 


library control index is not valid, 
library is not open. 

RFA is not valid. 
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LBR$RET_ 

.RMSSTV—Return VAX RMS 

Status Value 

Returns the status value from the last VAX RMS function performed 
by any Librarian subroutine. 

FORMAT 

LBR$RET_RMSSTV 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

None. 


DESCRIPTION The LBR$RET_RMSSTV routine returns, as the status value, the status of the 

last RMS operation performed by the librarian. RMS status codes are defined 



by the $RMSDEF macro is SYS$LIBRARY:STARLET.MLB. 

CONDITION 

VALUES 

RETURNED 

Any condition values returned by VAX RMS routines. 
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LBR$SEARCH—Search an Index 



Finds index keys that point to specified data. 

FORMAT 

LBR$SEARCH library-index ,index-number 
,rfa-to-find,routine-name 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI_CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

index-number 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library index number. The index-number argument is the address of 
a longword that contains the number of the index you want to search (see 
Section 1.2.3). 

rfa-to- find 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

The record's file address (RFA) of the module whose keys you are searching 
for. The rfa-to-find argument is the address of a 2-longword array that 
contains the RFA (returned earlier by LBR$LOOKUP_KEY or 
LBR$PUT_RECORD) of the module header. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


routine-name 


VMS Usage: 
type: 
access: 
mechanism: 


procedure 

procedure entry mask 
read only 
by reference 


The name of a routine to process the keys. The routine-name argument is 
the address of the entry mask of a user-written routine to call for each key 
entry containing the RFA (in other words, for each key that points to the 
same module header). 

This user-written routine cannot contain any calls to LBR$DELETE_KEY or 
LBR$INSERT_KEY. 


Use LBR$SEARCH to find index keys that point to the same module header. 
Generally, in index number 1 (the module name table), just one key points 
to any particular module; thus, you would probably use this routine only 
to search library indexes where more than one key points to a module. 

For example, you might call LBR$SEARCH to find all the global symbols 
associated with an object module in an object library. 

If LBR$SEARCH finds an index key associated with the specified RFA, it calls 
a user-supplied routine with two arguments. 

1 The key argument is the address of either: 

• A string descriptor for the keyname (libraries with ASCII keynames). 

• An unsigned longword for the key value (libraries with binary keys). 

2 The RFA. The RFA argument is the address of a 2-longword array which 
contains the RFA of the module header. 

The routine must return a value to indicate success or failure. If the specified 
routine returns a false value (low bit = 0), then the index search terminates. 

Note that the key found by LBR$SEARCH is valid only during the call to the 
user-supplied routine. If you want to use the key later, you must copy it. 


LBR$_ILLCTL 

LBR$_ILLIDXNUM 

LBR$_KEYNOTFND 

LBR$_LIBNOTOPN 


The specified library control index is not valid. 
The specified library index number is not valid. 

The librarian did not find any keys with the 
specified RFA. 

The specified library is not open. 
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LBR$SET_INDEX—Set the Current Index 

Number 

Sets the index number to use during processing of libraries that have 
more than one index. 

FORMAT 

LB R$SET_I N D EX library-index, index-number 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

index-number 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The index number you want to establish as the current index number. The 
library-index is the address of a longword that contains the number of the 
index you want to establish as the current index. (See Section 8.1.2.3.) 

DESCRIPTION 

When you call LBR$INI—CONTROL, the librarian sets the current library 
index to 1 (the module name table, unless the library is a user-developed 
library). If you need to process another library index, you must use 
LBR$SET_INDEX to change the current library index. 

Note that macro, help, and text libraries contain only one index; therefore, 
you do not need to call LBR$SET_INDEX. Object libraries contain two 
indexes. If you want to access the global symbol table, you must call the 
LBR$SET_INDEX routine to set the index number. User-developed libraries 
can contain more than one index; therefore, you may need to call 

LBR$SET_INDEX to set the index number. 
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Upon successful completion, LBR$SET_INDEX sets the current library index 
to the requested index number. The librarian routines number indexes 
starting with 1. 


CONDITION 

LBR$_ILLCTL 

The 

VALUES 

LBR$_ILLIDXNUM 

The 

RETURNED 

LBR$_LIBNOTOPN 

The 


specified library control index is not valid, 
library index number specified is not valid, 
specified library is not open. 
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LBR$SET_LOCATE—Set Record Access to 



Locate Mode 

Sets the record access of librarian subroutines to locate mode. 

FORMAT 

LBR$SET_LOCATE library-index 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI_CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

DESCRIPTION 

Librarian record access may be set to move mode (the default, set by 
LBR$SET_MOVE) or locate mode. The setting affects the operation of the 
LBR$GET_RECORD routine. 

If move mode is set (the default), LBR$GET__RECORD will copy the requested 
record to the specified user buffer. If locate mode is set, the record is not 
copied. Instead, the outbufdes descriptor is set to reference an internal 
librarian subroutine buffer which contains the record. 

CONDITION 

VALUES 

RETURNED 

LBR$_ILLCTL The specified library control index is not valid. 

LBR$_LIBNOTOPN The specified library is not open. 
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LBR$SET_ 

-MODULE—Read or Update a 

Module Header 

Reads, and optionally updates, the module header associated with a 
given record's file address (RFA). 

FORMAT 

LBR$SET_MODULE library-index ,rfa [,bufdesc] 

[, buflen] [, updatedesc] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI—CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 

rfa 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

The record's file address (RFA) associated with the module header. The rfa 
argument is the address of a 2-longword array containing the RFA which was 
returned by LBR$PUT_RECORD or LBR$LOOKUP_KEY. 

bufdesc 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

The buffer that receives the module header. The bufdesc argument is the 
address of a string descriptor pointing to the buffer that receives the module 
header. The buffer must be the size specified by the symbol 
MHD$B_USRDAT plus the value of the CRE$L_UHDMAX create option. 
The MHD$ and CRE$ symbols are defined in the modules $MHDDEF and 
$CREDEF, which are stored in SYS$LIBRARY:STARLET.MLB. 
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LBR$SET_MODULE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


buflen 

VMS Usage: 
type: 
access: 
mechanism: 


longword—signed 
longword (signed) 
write only 
by reference 


The length of the module header. The buflen argument is the address of a 
longword that receives the length of the returned module header. 


updatedesc 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Additional information for the module header. The updatedesc argument is 
the address of a string descriptor pointing to additional data that the librarian 
stores with the module header. If you include this argument, the librarian 
will update the module header with the additional information. 


If you specify bufdesc, the librarian routine will return the module header 
into the buffer. If you specify buflen, the librarian routine will also return the 
buffer's length. If you specify updatedesc, the routine will update the header 
information. 

You define the maximum length of the update information (by specifying a 
value for CRE$L_UHDMAX) when you create the library. The librarian will 
zero-fill the information if it is less than the maximum length, or will truncate 
it if it exceeds the maximum length. 


LBR$_HDRTRUNC 

LBRSILLCTL 

LBR$_ILLOP 

LBR$_INVRFA 
LBR$_LIBNOT OPN 


The buffer supplied to hold the module header was 
too small. 

The specified library control index is not valid. 

The updatedesc argument was supplied and the 
library was a Version 1.0 library or the library was 
opened only for read access. 

The specified RFA does not point to a valid module 
header. 

The specified library is not open. 
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LBR$SET_ 

-MOVE—Set Record Access to 
Move Mode 

Sets the record access of librarian subroutines to move mode. 

FORMAT 

LBR$SET_MOVE library-index 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

library-index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The library control index which was returned by the LBR$INI_CONTROL 
routine. The library-index argument is the address of a longword that 
contains the index. 


DESCRIPTION Librarian record access may be set to move mode (the default, set by 

LBR$SET_MOVE) or locate mode. The setting affects the operation of the 



LBR$GET_RECORD routine. If move mode is set, LBR$GET_RECORD will 
copy the requested record to the specified user buffer. For details, see the 
description of LBR$GET_RECORD. 

CONDITION 

VALUES 

RETURNED 

LBR$_ILLCTL The specified library control index is not valid. 

LBR$_LIBNOTOPN The specified library is not open. 
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Print Symbiont Modification (PSM) Routines 


9.1 





Introduction to PSM Routines 

The print symbiont modification (PSM) routines allow you to modify the 
behavior of the print symbiont that is supplied with the VAX/VMS operating 
system. 

The VAX/VMS print symbiont processes data for output to standard line 
printers and printing terminals. It performs the following functions: 

• Reads the data from disk 

• Formats the data 

• Sends the data to the printing device 

• Composes separation pages (flag, burst, and trailer pages) and inserts them 
into the data stream for printing 

Some of the reasons for modifying the print symbiont include the following: 

• You want the separation pages (flag, burst, and trailer pages) to include 
additional information or to be formatted differently 

• You want to filter and modify the data stream sent to the printer 

• You want to change some of the ways that the symbiont controls the 
printing device 

You might not always be able to modify the print symbiont to suit your 
needs. For example, you cannot make the following modifications: 

• Modify the VAX/VMS symbiont's control logic or the sequence in which 
the symbiont calls routines. 

• Modify the interface between the VAX/VMS symbiont and the job 
controller. 

If you cannot modify the VAX/VMS print symbiont to suit your needs, you 
might want to write your own symbiont. Section 9.3 describes how to write 
your own symbiont and integrate it with the VAX/VMS operating system. 
However, it is recommended that you modify the VAX/VMS print symbiont, 
when possible, rather than write your own symbiont. 

The following list describes the content of the remaining major sections on 
PSM routines: 

• Section 9.2 contains an overview of the VAX/VMS print symbiont and 
of symbionts in general. It explains concepts such as "symbiont streams"; 
describes the relationship between a symbiont, a device driver, and the 
job controller; and gives an overview of the VAX/VMS print symbiont's 
internal logic. 

This section is recommended for those who want either to modify the 
VAX/VMS print symbiont or to write a new symbiont. 
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• Section 9.3 details the procedure to follow in modifying the VAX/VMS 
print symbiont. It includes an overview of the entire procedure, followed 
by a detailed description of each step. 

• Section 9.4 contains an example of a simple modification to the VAX/VMS 
print symbiont. 

• Section 9.5 describes each PSM routine, and describes the interface that 
routines you substitute for the standard PSM routines must use. 


9.2 VAX/VMS Print Symbiont Overview 

This section describes the VAX/VMS print symbiont, which is an output 
symbiont. An output symbiont receives tasks from the job controller, whereas 
an input symbiont sends jobs to the job controller. 

There are two types of output symbiont: device symbionts and server 
symbionts. A device symbiont processes data for output to a device. A server 
symbiont also processes data, but not necessarily for output to a device. One 
example of a server symbiont is a symbiont that copies files across a network. 
The VAX/VMS operating system supplies no server symbionts. 

The VAX/VMS operating system supplies two symbionts: a print symbiont 
and a card reader symbiont. The card reader symbiont, which is an input 
symbiont, cannot be modified. The print symbiont, which is an output device 
symbiont, can be modified using the PSM routines. 


9.2.1 Components of the VAX/VMS Print Symbiont 

The VAX/VMS print symbiont includes the following major components: 

• PSM routines that are used to modify the print symbiont 

• Routines that implement input, format, and output services in the 
VAX/VMS print symbiont 

• Routines that implement the internal logic of the VAX/VMS print 
symbiont 

The VAX/VMS print symbiont is implemented using the Symbiont Services 
Facility. This facility provides communication and control between the job 
controller and symbionts through a set of Symbiont/Job-Controller Interface 
Routines (SMB routines), which are documented in Section 10. 

All the routines described above are contained in a shareable image with the 
file specification SYS$SHARE:SMBSRVSHR.EXE. 
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9.2.2 Creation of the Print Symbiont Process 

The print symbiont is a device symbiont, receiving tasks from the job 
controller and processing them for output to a printing device. In the 
VAX/VMS operating system, the existence of a print symbiont process is 
linked to the existence of at least one print execution queue that is started. 

The job controller creates the print symbiont process by calling the Create 
Process ($CREPRC) system service; it does this whenever either of the 
following conditions occur: 

• A print execution queue is started (from the stopped state) and no 
symbiont process is running the image specified with the START/QUEUE 
command. 

A print execution queue is started by means of the DCL command START 
/QUEUE. The /PROCESSOR qualifier can be used with the START 
/QUEUE command to specify the name of the symbiont image that is to 
service an execution queue; if /PROCESSOR is omitted, then the default 
symbiont image is PRTSMB. 

• Currently existing symbiont processes suited to a print execution queue 
cannot accept additional devices; that is, the symbionts have no more 
available streams. In such a case, the job controller creates another print 
symbiont process. The next section discusses symbiont streams. 

The print symbiont process runs as a detached process. 


9.2.3 Symbiont Streams 

A stream is a logical link between a print execution queue and a printing 
device. When the queue is started (by means of START/QUEUE), the job 
controller creates a stream linking the queue with a symbiont process. Since 
each print execution queue has a single associated printing device (specified 
with the /ON=device_name qualifier with the INITIALIZE/QUEUE or 
START/QUEUE commands), each stream created by the job controller will 
link a print execution queue, a symbiont process, and the queue's associated 
printer. 

A symbiont that can support multiple streams simultaneously (that 
is, multiple print execution queues and multiple devices) is termed a 
multithreaded symbiont. The job controller enforces an upper limit on 
the number of streams that any symbiont can service simultaneously; this 
limit is 16. 

Therefore, in the VAX/VMS operating system environment, only one print 
symbiont process is needed so long as the number of print execution queues 
(and associated printers) does not exceed 16. If there are more than 16 
print execution queues, the job controller will create another print symbiont 
process. 

The VAX/VMS print symbiont is, therefore, a multithreaded symbiont, that 
can service as many as 16 queues and devices, but you can modify it to 
service any number of queues and devices so long as the number is less than 
or equal to 16. 
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A symbiont stream is said to be "active" when a queue is started on that 
stream. The print symbiont maintains a count of active streams. It increments 
this count each time a queue is started and decrements it when a queue is 
stopped with the DCL command STOP/QUEUE/NEXT or STOP/QUEUE 
/RESET. When the count falls to zero, the symbiont process exits. The 
symbiont does not decrement the count when the queue is paused by STOP 
/QUEUE. 

Figure PSM-1 shows the relationship between generic print queues, execution 
print queues, the job controller, the print symbiont, printer device drivers, 
and printers. The dotted lines connecting the boxes denote streams. 

Figure PSM-1 Multithreaded Symbiont 
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9.2.4 Symbiont and Job Controller Functions 

This section compares the roles of the symbiont and job controller in the 
execution of print requests. Print requests are issued using the PRINT 
command. 

The job controller uses the information specified on the PRINT command line 
to determine the following: 

• Which queue to place the job in (/QUEUE, /REMOTE, /LOWERCASE, 
and /DEVICE) 

• How many copies to print (/COPIES and /JOB_COUNT) 

• Scheduling constraints for the job (/PRIORITY, /AFTER, 

/BLOCK_LIMIT, /HOLD, /FORM, /CHARACTERISTICS, and 
/RESTART) 

• How and whether to display the status of jobs and queues (/NOTIFY, 
/OPERATOR, and /IDENTIFY) 

The print symbiont, on the other hand, interprets the information supplied 
with the qualifiers that specify this information: 

• Whether to print file separation pages (/BURST, /FLAG, and /TRAILER) 

• Information to include when printing the separation pages (/NAME and 
/NOTE) 

• Which pages to print (/PAGES) 

• How to format the print job (/FEED, /SPACE, and /PASSALL) 
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• How to set up the job (/SETUP) 

The print symbiont, not the job controller, performs all necessary device- 
related functions. It communicates with the printing device driver. For 
example, when a print execution queue is started (by means of START 
/QUEUE/ON=device_name) and the stream is established between the 
queue and the symbiont, the symbiont parses the device name specified by 
the /ON qualifier in the START/QUEUE command, allocates the device, 
assigns a channel to it, obtains the device characteristics, and determines the 
device class. In versions of the VAX/VMS operating system prior to Version 
4.0, the job controller performed these functions. 

The print symbiont's output routine returns an error to the job controller if 
the device class is neither "printer" nor "terminal". 


9.2.5 Print Symbiont Internal Logic 

The job controller deals with units of work called jobs, while the print 
symbiont deals with units of work called tasks. A print job can consist 
of several print tasks. Thus, in the processing of a print job, it is the job 
controller's role to divide a print job into one or more print tasks, which the 
symbiont can process. The symbiont reports the completion of each task to 
the job controller, but the symbiont contains no logic to determine that the 
print job as a whole is complete. 

In the processing of a print task, the symbiont performs three basic functions: 
input, format, and output. The symbiont performs these functions by calling 
routines to perform each function. 

The following steps describe the action taken by the symbiont in processing a 
task: 

1 The symbiont receives the print request from the job controller and stores 
it in a message buffer. 

2 The symbiont searches its list of input routines and selects the first input 
routine that is applicable to the print task. 

3 The input routine returns a data record to the symbiont's input buffer or 
in a buffer supplied by the input routine. 

4 Data in the input buffer is moved to the symbiont's output buffer by the 
formatting routines, which format it in the process. 

5 Data in the output buffer is sent to the printing device by the output 
routine. 

6 When an input routine completes execution, that is, when it has no 
more input data to process, the symbiont selects another applicable input 
routine. Steps 3, 4, and 5 are repeated until all applicable input routines 
have executed. 

7 The symbiont informs the job controller that the task is complete. 

Figure PSM-2 pictures the steps taken by the symbiont in the processing of a 
print task: 
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Figure PSM-2 Symbiont Execution Sequence or Flow of 
Control 


INPUT 

ROUTINES 



. . .and so on 
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As Figure PSM-2 shows, most of the input routines execute in a specified 
sequence. This sequence is defined by the symbiont's main control routine. 
You cannot modify this main control routine, and so you cannot modify the 
sequence in which symbiont routines are called. 

The input routines that do not execute in sequence are called "demand input 
routines"; these routines are called whenever the service they provide is 
required. The demand input routines include the page header, page setup, 
and library module input routines. 

The symbiont can perform input, formatting, and output functions 
asynchronously; that is, the order in which the symbiont calls the input, 
formatting, and output routines can vary. For example, the symbiont can call 
an input routine, which returns a record to the input buffer; it can then call 
the format routine, which moves that record to the output buffer; and then 
it can call the output routine to move that data to the printing device. This 
sequence results in the movement of a single data record from disk to printing 
device. 

On the other hand, the symbiont can call the input and formatting routines 
several times before calling the output routine for a single buffer. The buffer 
can contain one or more formatted input records. In some cases an output 
buffer might contain only a portion of an input record. 

In this way the symbiont can buffer input records; then call the format 
routine, which moves one of those records to the output buffer; and finally 
call the output routine, which moves that data to the printing device. Note, 
however that the formatting routine must be called once for each input 
record. 

Similarly, the symbiont can buffer several formatted records before calling the 
output routine to move them to the printing device. 
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The symbiont requires this flexibility in altering the sequence in which input, 
format, and output routines are called for reasons of efficiency (high rate of 
throughput) and adaptability to various system parameters and system events. 

The value specified with the call to PSM$PRINT determines the maximum 
size of the symbiont's output buffer, which cannot be larger than the value 
of the SYSGEN parameter MAXBUF. If the buffer is very small, the symbiont 
might need to call its output routine one or more times for each record 
formatted. If the buffer is large, the symbiont will buffer several formatted 
records before calling the output routine to move them to the printing device. 


9.3 Modification Procedure 


9.3.1 Overview 


To modify the VAX/VMS print symbiont, perform the following steps. These 

steps are described in more detail in the sections that follow. 

1 Determine the modification needed. The modification might involve 
changing the way the symbiont performs a certain function, or it might 
involve adding a new function. 

2 Determine where to make the modification. This involves selecting 
a function and determining where that function is performed within 
the symbiont's execution sequence. You specify a function by calling 
the PSM$REPLACE routine and specifying the code that identifies the 
function. 

Some codes correspond to symbiont-supplied routines. When you specify 
one of these codes, you replace that routine with your routine. Other 
codes do not correspond to symbiont-supplied routines. When you 
specify one of these codes, you add your routine to the set of routines the 
symbiont executes. Table PSM-1 lists these codes. 

3 Write the routine. Since the symbiont calls your routine, your routine 
must have one of three call interfaces, depending on whether it is an 
input, format, or output routine. See the descriptions of the USER-INPUT- 
ROUTINE, USER-FORMAT-ROUTINE, and USER-OUTPUT-ROUTINE 
routines, which follow the descriptions of the PSM routines. 

4 Write the symbiont-initialization routine. This routine executes when the 
symbiont is first activated by the job controller. It initializes the symbiont's 
internal database; specifies, by calling PSM$REPLACE, the routines 

you have supplied; activates the symbiont by calling PSM$PRINT; and 
performs any necessary cleanup operations when PSM$PRINT completes. 

5 Construct the modified symbiont. This involves compiling your routines, 
then linking them. 

6 Integrate the modified symbiont with the system. This involves placing 
the executable image in SYS$SYSTEM, identifying the symbiont image to 
the job controller, and debugging the symbiont. 
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As mentioned previously, you identify each routine you write for the 
symbiont by calling the PSM$REPLACE routine. The code argument for 
this routine specifies the point within the symbiont's execution sequence 
at which you want your routine to execute. You should know which code 
you will use to identify your routine before you begin to write the routine. 
Section 9.3.6 provides more information about these codes. 


9.3.2 Guidelines and Restrictions 

The following guidelines and restrictions apply to the writing of any symbiont 

routine: 

• Do not use the process-permanent files identified by the logical names 
SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND. 

• Do not use the system services SYS$HIBER and SYS$WAKE. 

• Use the following two Run-Time-Library routines for allocation and 
deallocation of memory: LIB$GET_VM and LIB$FREE_VM. 

• Minimize the amount of time that your routine spends executing at AST 
level. The job controller sends messages to the symbiont by means of 
user-mode ASTs; the symbiont cannot receive these ASTs while your user 
routine is executing at AST level. 

• The symbiont can call your routines at either AST level or non-AST level. 

• If your routine returns any error-condition-value (low bit clear), the 
symbiont aborts the current task and notifies the job controller. Note that 
by default an error-condition-value returned during the processing of a 
task causes the job controller to abort the entire job. However, this default 
behavior may be overridden. See the description of the /RETAIN qualifier 
of the DCL commands START/QUEUE, INITIALIZE/QUEUE, and SET 
QUEUE in the VAX/VMS DCL Dictionary . 

The symbiont stores the first error-condition-value (low bit clear) returned 
during the processing of a task. The symbiont's file-errors routine, an 
input routine (code PSM$K_FILE—ERRORS), places the message-text 
associated with this condition value in the symbiont's input stream. The 
symbiont prints this text at the end of the listing, immediately before the 
trailer pages. 

The symbiont sends this error-condition-value to the job controller; the 
job controller then stores this condition value with the job record in the 
job controller's queue file. The job controller also writes this condition 
value in the accounting record for the job. 

It is recommended that, if you choose to return a condition value when 
an error occurs, you choose one from the system message file. This 
allows system programs to access the message-text associated with 
the condition value. Specifically, the Accounting and SHOW/QUEUE 
utilities and the job controller will be able to translate the condition value 
to its corresponding message-text and to display this message-text as 
appropriate. 

• This guideline applies to input, input-filter, and output-filter routines, and 
to the symbiont's use of dynamic string descriptors in these routines. 
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The simplest way for an input routine to pass the data record to the 
symbiont is for it to use an RTL string-handling routine (for example, 
STR$COPY_R). These routines use dynamic string descriptors to point to 
the record they have handled to copy the record from your input buffer 
to the symbiont-supplied buffer specified in the funcdesc argument to the 
input routine. 

By default, the symbiont initializes a dynamic string descriptor that your 
input routine can use to describe the data record it returns. Specifically, 
the symbiont initializes the DSC$B_DTYPE field of the string descriptor 
with the value DSC$K_DTYPE_T (which indicates that the data to which 
the descriptor points is a string of characters) and initializes the 
DSC$B_CLASS field with the value DSC$K_CLASS—D (which indicates 
that the descriptor is dynamic). 

Alternatively, the input routine can pass a data record to the symbiont 
by providing its own buffer and passing a static string descriptor that 
describes the buffer. To do this, you must redefine as follows the fields of 
the descriptor to which the funcdesc argument points: 

1 Initialize the field DSC$B_CLASS with the value 
DSC$K_CLASS_S (which indicates that the descriptor points to a 
scalar value or a fixed-length string). 

2 Initialize the field DSC$A_POINTER with the address of the buffer 
that contains the data record. 

3 Initialize the field DSC$W_LENGTH with the length, in bytes, of the 
data record. 

Each time the symbiont calls the routine to read some data, the symbiont 
reinitializes the descriptor to be a dynamic descriptor. Consequently, if 
you want to use the descriptor as a static descriptor, your input routine 
must initialize the descriptor as described above every time it is called to 
perform a reading operation. 

Input-filter routines and output-filter routines return a data record to 
the symbiont by means of the func_desc_2 argument. The symbiont 
initializes a descriptor for this argument the same way it does for 
descriptors used by input routine described above. Thus the guidelines 
described for the input routine apply to the input-filter routine and 
output-filter routine. 


9.3.3 Writing an Input Routine 

To write an input routine, follow the modification procedure described in 
Section 9.3. 

This section provides additional information on the writing of an input 
routine. It provides an overview of the logic used in the VAX/VMS print 
symbiont's main input routine, and it discusses the way in which the 
VAX/VMS print symbiont handles carriage-control effectors. 

The print symbiont calls your input routine, supplying it with arguments. 
Your routine must return arguments and condition values to the print 
symbiont. For this reason, your input routine must use the interface described 
in the description of the USER-INPUT-ROUTINE. 

When the print symbiont calls your routine, it specifies a particular request in 
the func argument. Each function has a corresponding code. 
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Your routine must provide the functions identified by the codes 
PSM$K_OPEN, PSM$K__READ, and PSM$K_CLOSE. Your routine need 
not respond to the other function codes, but it can if you want it to. If your 
routine does not provide a function that the symbiont requests, it must return 
the condition value PSM$_FUNNOTSUP to the symbiont. 

The description of the func argument of the USER-INPUT-ROUTINE 
describes the codes that the symbiont can send to an input routine. 

See Section 9.3.6 for additional information about other function codes used 
in the user-written input routine. 

For each task that the symbiont processes, it calls some input routines only 
once, and some more than once; it always calls some routines, and calls 
others only when needed. 

Table PSM-1 lists the codes that you can specify when you call the 
PSM$REPLACE routine to identify your input routine to the symbiont. 

The description of the PSM$REPLACE routine describes these routines. 


9.3.3.1 Internal Logic of the Symbiont's Main Input Routine 

The internal logic of the symbiont's main input routine, as described in this 
section, is subject to change without notice. This logic is summarized here. 
This summary is not intended as a tutorial on the writing of a symbiont's 
main input routine, although it does provide insight into such a task. 

A main input routine is the routine that the symbiont calls to read data from 
the file that is to be printed. A main input routine must perform three sets 
of tasks: one set when the symbiont calls the routine with an OPEN request, 
one set when the symbiont calls with a READ request, and one set when the 
symbiont calls with a CLOSE request. 

The following list names the codes that identify each of these three requests 
and describes the tasks that the VAX/VMS symbiont's main input routine 
performs for each of these requests: 


Code Action Taken by the Input Routine 

PSM$K_OPEN An OPEN request. When the main input routine receives this 
request code, it does the following: 

1 Opens the input file. 

2 Stores information about the input file. 

3 Returns the type of carriage control used in the input file. 
If this routine cannot open the file, it returns an error. 
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Code 

Action Taken by the Input Routine 

Note: 

The VMS print symbiont's main input routine 
performs these tasks when it receives the 

PSM$K—START—TASK function code, rather than 
the PSM$K—OPEN function code. 


This atypical behavior occurs because some of the 
information stored by the main input routine must be 
available for other input routines that execute before 
the main input routine. For example, information 
about file attributes, record formats, and so on, is 
needed by the symbiont's separation-page routines, 
which print flag and burst pages. 

Consequently, if you supply your own main input 
routine, some of the information about the file being 
printed that appears on the standard separation pages 
is not available, and the symbiont prints a message on 
the separation page stating so. 


The symbiont receives the file-identification number from 
the job controller in the SMBMSG$K_FILE_IDENTIFICATION 
item of the requesting message and uses this value rather 
than the file specification to open the main input file. 

PSM$K_READ 

A READ request. When the main input routine receives this 
request, it returns the next record from the file. In addition, 
when the carriage control used by the data file is 
PSM$K_CC_PRINT, the main input routine returns the 
associated record header. 

PSM$K_CLOSE 

A CLOSE request. When the main input routine receives this 
request, it closes the input file. 


9.3.3.2 Symbiont Processing of Carriage Control 

Each input record can be thought of as consisting of three parts: leading 
carriage control, data, and trailing carriage control. Taken together, these 
three parts are called the composite data record. 

Leading and trailing carriage control are determined by the type of carriage 
control used in the file and explicit carriage-control information returned with 
each record. For embedded carriage control, however, leading and trailing 
carriage control is always null. 

The type of carriage control returned by the main input routine on the 
PSM$K_OPEN request code determines, for that invocation of the input 
routine, how the symbiont applies carriage control to each record that the 
main input routine returns on the PSM$K_READ request code. 

Note that, for all four carriage control types, the first character returned on 
the first PSM$K_READ call to an input routine receives special processing. If 
that character is a linefeed or a formfeed, and if the symbiont is currently at 
line 1, column 1 of the current page, then the symbiont discards that linefeed 
or formfeed. 
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The Four Types of Carriage Control 

The following list briefly describes each type of carriage control and how the 
symbiont's main input routine processes it. For a detailed explanation of each 
of these types of carriage control, refer to the description of the 
FAB$B__RAT field of the FAB block in the VAX Record Management Services 
Reference Manual. 


Type of Carriage Control Symbiont Processing 


Embedded 

Leading and trailing carriage control are embedded 
in the data portion of the input record. Therefore, 
the symbiont supplies no special carriage control 
processing; it assumes that leading and trailing 
carriage control are null. 

FORTRAN 

The first byte of each data record contains 
a FORTRAN carriage-control character. This 
character specifies both the leading and trailing 
carriage control for the data record. The symbiont 
extracts the first byte of each data record and 
interprets that byte as a FORTRAN carriage- 
control character. If the data record is empty, the 
symbiont generates a leading carriage control of 
linefeed and a trailing carriage control of carriage 


return. 

PRN 

Each data record contains a two-byte header that 
contains the carriage-control specifier. The first 
byte specifies the carriage control to apply before 
printing the data portion of the record. The second 
byte specifies the carriage control to apply after 
printing the data portion. The abbreviation PRN 
stands for print-file format. 


Unlike other types of carriage control, PRN carriage 
control information is returned through the funcarg 
argument of the main input routine; this occurs 
with the PSM$K_READ request. The funcarg 
argument specifies a longword; your routine writes 
the 2-byte PRN carriage control specifier into the 
first two bytes of this longword. 

Implied 

The symbiont provides a leading linefeed and 
a trailing carriage return. But if the data record 
consists of a single formfeed, the symbiont sets 
to null the leading and trailing carriage control for 
that record, and the leading carriage control for the 
record that follows it. 


9.3.4 Writing a Format Routine 

To write a format routine, you follow the modification procedure described in 
Section 9.3. Do not replace the VAX/VMS symbiont's main format routine. 
Instead, modify its action by writing input and output filter routines. These 
execute immediately before and after the main format routine, respectively. 
The main formatting routine uses an undocumented and nonpublic interface, 
you may not replace the main formatting routine. The DCL command PRINT 
/PASSALL bypasses the main format routine of the print symbiont. 
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See Section 9.3.6 for additional information about other function codes used 
in the user-written formatting routine. 


9.3.4.1 Internal Logic of the Symbiont's Main Format Routine 

The main format routine contains all the logic necessary to convert composite 
data records to a data stream for output. Actions taken by the format routine 
include the following: 

• Tracking the current column and line 

• Implementing the special processing of the first character of the first record 

• Implementing the alignment data mask specified by the DCL command 
START/QUEUE/ALIGN=M ASK 

• Handling margins as specified by the forms definition 

• Initiating processing of page headers when specified by the DCL command 
PRINT/HEADER 

• Expanding leading and trailing carriage control 

• Handling line overflow 

• Handling page overflow 

• Expanding tab characters to spaces for some devices 

• Handling escape sequences 

• Accumulating accounting information 

• Implementing double-spacing when specified by the DCL command 
PRINT/SPACE 

• Implementing automatic page ejection when specified by the DCL 
command PRINT/FEED 

The symbiont's main format routine uses a special rule when processing 
the first character of the first composite data record returned by an input 
routine. (A composite data record is the input data record and a longword 
that contains carriage-control information for the input data record.) This rule 
is that if this first character is a vertical format effector (formfeed or linefeed) 
and if the symbiont has processed no printable characters on the current page 
(that is, the current position is column 1, line 1), then that vertical format 
effector is discarded. 


9.3.5 Writing an Output Routine 

To write an output routine, you follow the modification procedure described 
in Section 9.3. 

The print symbiont is the caller of your output routine. Input arguments 
are supplied by the print symbiont; output arguments and status values are 
returned by your routine to the print symbiont. For this reason, your output 
routine must have the call interface that is described in the USER-OUTPUT- 
ROUTINE routine. 

When the print symbiont calls your routine, it specifies in one of the input 
arguments, the func argument, the reason for the call. Each reason has a 
corresponding function code. 
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There are several function codes that the print symbiont can supply when it 
calls your output routine. Your routine must contain the logic to respond to 
the following function codes: PSM$K_OPEN, PSM$K_WRITE, 
PSM$K_WRITE-NOFORMAT, and PSM$K_CLOSE. 

It is not required that your output routine contain the logic to respond to the 
other function codes, but you can provide this logic if you want to. 

A complete list and description of all relevant function codes for output 
routines is provided in the description of the func argument in the description 
of the USER-OUTPUT-ROUTINE routine. 

See Section 9.3.6 for additional information about other function codes. 


9.3.5.1 Internal Logic of the Symbiont's Main Output Routine 

When the symbiont calls the main output routine with the PSM$K_OPEN 
function code, the main output routine takes the following steps: 

1 Allocates the print device 

2 Assigns a channel to the device 

3 Obtains the device characteristics 

4 Returns the device-status longword in the funcarg argument (see the 
description of the SMBMSG$K—DEVICE—STATUS message item in 
Section 10, Symbiont/Job-Controller Interface (SMB) Routines, for more 
information) 

5 Returns an error if the device is not a terminal or a printer 

When this routine receives a PSM$K_WRITE service request code, it sends 
the contents of the symbiont output buffer to the device for printing. 

When this routine receives a PSM$K_WRITE—NOFORMAT service request 
code, it sends the contents of the symbiont output buffer to the device for 
printing and suppresses device drive formatting as appropriate for the device 
in use. 

When this routine receives a PSM$K_CANCEL service request code, it 
requests the device driver to cancel any outstanding output operations. 

When this routine receives a PSM$K_CLOSE service request code, it 
deassigns the channel to the device and deallocates the device. 


9.3.6 Other Function Codes 

Whenever the symbiont notifies user-written input, output, and format 
routines using the following message function codes, a status 
PSM$_PENDING may not be returned. 
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Function Code 

Description 

PSM$K_ST ART_STRE AM 

Job controller sends a message to the symbiont to 
start a queue. 

PSM$K_ST ART_T ASK 

Symbiont parses message from job controller 
directing it to start a queue. 

PSM$K_PAUSE_T ASK 

Job controller sends message to the symbiont to 
suspend processing of the current task. 

PSM$K_STOP_STREAM 

Job controller sends message to the symbiont to 
stop the queue. 

PSM$K_STOP_TASK 

Job controller sends a message to the symbiont to 
stop the task. 

PSMSK -RESUME _T ASK 

Job controller sends a message to the symbiont to 
resume processing of the current task. 

PSM$K_RESET_STREAM 

Same as PSM$K_STOP_STREAM 


9.3.7 Writing a Symbiont Initialization Routine 

Writing a symbiont initialization routine involves writing a program which 
does the following: 

1 Calls PSM$REPLACE once for each routine (input, output, or format) 
that you have written. PSM$REPLACE identifies your routines to the 
symbiont. 

2 Calls PSM$PRINT exactly once after you have identified all your service 
routines using PSM$REPLACE. 

Table PSM-1 lists all routine codes that you can specify in the 
PSM$REPLACE routine. Choosing the correct routine code for your routine 
is important because the routine code specifies when the symbiont will call 
your routine. The functions of these routines are described further in the 
description of the PSM$REPLACE routine. 

Column one in Table PSM-1 lists each routine code. 

For those input routines that execute in a predefined sequence, the second 
column contains a number showing the order in which that input routine is 
called relative to the other input routines for a single file job. If the routine 
does not execute in a predefined sequence, the second column contains the 
character "x". 

Column three specifies whether the routine is an input, format, or output 
routine; this information directs you to the section describing how to write a 
routine of that type. 

Column four specifies whether there is a symbiont-supplied routine 
corresponding to that routine code. The codes for the input-filter and output- 
filter routines, which have no corresponding routines in the VAX/VMS 
symbiont, allow you to specify new routines for inclusion in the symbiont. 
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Table PSM-1 Routine Codes for Specification to 
PSM$REPLACE 


Routine Code 

Sequence 

Function 

Supplied 

PSM$K_JOB_SETUP 

1 

Input 

Yes 

PSM$K_FORM_SETUP 

2 

Input 

Yes 

PSM$K_JOB_FLAG 

3 

Input 

Yes 

PSM$K_JOB_BURST 

4 

Input 

Yes 

PSM$K_FILE_SETUP 

5 

Input 

Yes 

PSM$K_FILE_FLAG 

6 

Input 

Yes 

PSM$K_FILE_BURST 

7 

Input 

Yes 

PSM$K_FILE_SETUP_2 

8 

Input 

Yes 

PSM$K_MAIN_INPUT 

9 

Input 

Yes 

PSM$K_FILE—INFORMATION 

10 

Input 

Yes 

PSM$K_FILE_ERRORS 

11 

Input 

Yes 

PSM$K_FILE—TRAILER 

12 

Input 

Yes 

PSM$K_JOB—RESET 

13 

Input 

Yes 

PSM$K_JOB—TRAILER 

14 

Input 

Yes 

PSM$K_JOB—COMPLETION 

15 

Input 

Yes 

PSM$K_P AGE-SETUP 

X 

Input 

Yes 

PSM$K_P AGE-HEADER 

X 

Input 

Yes 

PSM$K_LIBRARY—INPUT 

X 

Input 

Yes 

PSMSK—INPUT—FILTER 

X 

Formatting 

No 

PSM$K_MAIN-FORMAT 

X 

Formatting 

Yes 

PSM$K_OUTPUT—FILTER 

X 

Formatting 

No 

PSM$K_OUTPUT 

X 

Output 

Yes 


9.3.8 Integrating a Modified Symbiont 

To integrate your user routine(s) and the symbiont initialization routine, 
perform the following steps; note that the sequence of steps described here 
assumes that you will be debugging the modified symbiont: 

1 Compile or assemble the user routine(s) and the symbiont initialization 
routine into an object module. 

2 Issue the following DCL command: 

$ LINK/DEBUG your-symbiont 

where the file name your-symbiont is the object module built in 
step 1. Symbols necessary for this link operation are located 
in the shareable images SYS$SHARE:SMBSRVSHR.EXE and 
SYS$LIBRARY:IMAGELIB.EXE. The linker automatically searches these 
shareable images and extracts the necessary information. 

3 Place the resulting executable symbiont image in SYS$SYSTEM:. 

4 Locate two unallocated terminals, one at which to issue DCL commands 
and one at which to debug the symbiont image. 
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5 Log in on one of the terminals under UIC [1,4], which is the system 
manager's account. This terminal is the one at which you will be issuing 
DCL commands. Do not log in at the other terminal. 

6 Issue the following DCL command: 

$ SET TERMINAL/NODISCONNECT/PERMANENT _TTcu: 

where _ TTcu: is the physical terminal name of the terminal at which you 
want to debug (the terminal you are not logged in at). 

7 Issue the following DCL commands: 

$ DEFINE/GROUP DBG$INPUT _TTcu: 

$ DEFINE/GROUP DBG$OUTPUT _TTcu: 

where —TTcu: specifies the physical terminal name of the terminal 
at which you will be debugging. The underscore (_) and colon (:) 
characters must be specified. Note that other users having a UIC with 
group number 1 should not use the debugger at the same time. 

8 Initialize the queue by issuing the following DCL command: 

$ INITIALIZE/QUEUE/PROCESSOR= your-symbiont /0N= printer_name 

The symbiont image specified by the file name your-symbiont must 
reside in SYS$SYSTEM:. Note too that the /PROCESSOR qualifier 
accepts only a file name; the device, directory, and file type are forced to 
SYS$SYSTEM:.EXE. 

The /ON qualifier specifies the device that will be served by the symbiont 
while you debug the symbiont. 

9 Enter the following DCL command to execute the modified symbiont 
routine: 

$ PRINT/HEADER/QUEUE=queue-id 

Issue the following DCL command to start the queue and invoke the 
debugger: 

$ START/QUEUE queue-name 

I 0 After you debug your symbiont, relink the symbiont by issuing the 

following DCL command: 

$ LINK/NOTRACEBACK/NODEBUG your-symbiont 

II Deassign the logical names DBG$INPUT and DBG$OUTPUT so that they 
will not interfere with other users in UIC group 1. 
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9>4 Example of Using the PSM Routines 

Example PSM-1 Using PSM Routines to Supply a Page Header 

Routine in a Macro Program 


.TITLE EXAMPLE - Example user modified symbiont 
.IDENT 'V03-000' 

++ 

THIS PROGRAM SUPPLIES A USER WRITTEN PAGE HEADER 
ROUTINE TO THE STANDARD SYMBIONT. THE PAGE HEADER 
INCLUDES THE SUBMITTER'S ACCOUNT NAME AND USER NAME, 
THE FULL FILE SPECIFICATION, AND THE PAGE NUMBER. 

THE HEADER LINE IS UNDERLINED BY A ROW OF DASHES 
PRINTED ON A SECOND HEADER LINE. 


System definitions 

IPSMDEF ; Symbiont definitions 

$SMBDEF ; Message item definitions 

$DSCDEF ; Descriptor definitions 


Define argument offsets for user supplied services called by symbiont 


CONTEXT 


= 04 

; symbiont context 

WORK.AREA 

= 08 

; user context 

FUNC 


= 12 

; function code 

FUNC.DESC 

= 16 

; function dependent descriptor 

FUNC.ARG 


= 20 

; function dependent argument 

Macro to create 

dynamic descriptors 


.MACRO D 

JDESC 



. 

WORD 

0 

; DSC$W_LENGTH = 0 

. 

BYTE 

DSC$K_DTYPE_T 

; DSC$B_DTYPE = STRING 

. 

BYTE 

DSC$K_CLASS_D 

; DSC$B_CLASS = DYNAMIC 

. 

LONG 

0 

; DSC$A_POINTER = 0 

. ENDM 




Storage for page header information 


FILE: 


D.DESC 

; file name descriptor 

USER: 


D.DESC 

; user name descriptor 

ACCOUNT: 


D.DESC 

; account name descriptor 

PAGE: 


.LONG 0 

; page number 

LINE: 


.LONG 0 

; line number 


FAO control string and work buffer. Header format: 
"[account.name] filename . Page 9999" 


FAO.CTRL: 
FA0_CTRL_2: 
FAO.DESC: 

FAO.BUFF: 


.ASCID /!71<[!AS, ! AS] 
.ASCID /!4UL/ 

.LONG 80 
.ADDRESS FAO.BUFF 
.BLKB 80 


!AS!>Page 9999/ 

; work buffer descriptor 
; work buffer 


(Continued on next page) 
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Example PSM-1 (Cont.) Using PSM Routines to Supply a Page 

Header Routine in a Macro Program 


Own storage for values passed by reference 



CODE: 

.LONG 0 

; service 

or item code 


STREAMS 

.LONG 1 

; number of simultaneous streams 


BUFSIZ: 

.LONG 2048 

; output buffer size 


LINSIZ: 

.WORD 81 

; line size for underlines 

; Main 

routine 

-- invoked at image startup 



START: 

.WORD 

0 ; save nothing because 

this routine uses only RO and R1 

; Supply private page header routine 




MOVZBL 

#PSM$K_PAGE_HEADER,CODE 

; set the 

service code 


PUSHAL 

HEADER 

; address 

of modified routine 


PUSHAL 

CODE 

; address 

of service code 


CALLS 

#2,G~PSM$REPLACE 

; replace 

the routine 


BLBC 

RO,10$ 

; exit if 

any errors 

; Transfer control to the standard symbiont 




PUSHAL 

BUFSIZ 

; address 

of output buffer size 


PUSHAL 

STREAMS 

; address 

of number of streams 


CALLS 

#2,G~PSM$PRINT 

; invoke i 

standard symbiont 

10$: 

RET 





Page header routine 


HEADER: 

.WORD 

0 

; save nothing 

$ 

; Check 

function code 


» 

CMPL 

#PSM$K_START_TASK.©FUNC(AP) 

; new task? 


BEQL 

20$ 

; branch if so 


CMPL 

#PSM$K_READ,©FUNC(AP) 

; READ function? 


BNEQ 

15$ 



BEQL 

50$ 

; branch if so 

15$: 

CMPL 

#PSM$K_0PEN, ©FUNC(AP) 

; OPEN function? 


BNEQ 

16$ 



BEQL 

66$ 

; branch if so 

16$: 

MOVL 

#PSM$_FUNNOTSUP,RO 

; unsupported function 


RET 


; return to symbiont 


(Continued on next page) 
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Example PSM-1 (Cont.) 


Using PSM Routines to Supply a Page 
Header Routine in a Macro Program 


Starting a new file 
20 $: 


CLRL 

MOVZBL 


PAGE 
#2,LINE 


reset the page number 
and the line number 


Get the account name 


MOVZBL 

#SMBMSG$K_ACCOUNT_NAME,CODE 

; set item code 

PUSHAL 

ACCOUNT 

; address of descriptor 

PUSHAL 

CODE 

; address of item code 

PUSHAL 

©CONTEXT(AP) 

; address of symbiont ctx value 

CALLS 

#3,G~PSM$READ_ITEM_DX 

; read it 

BLBC 

RO,40$ 

; branch if any errors 



Get the file name 


MOVZBL #SMBMSG$K_FILE_SPECIFICATION.CODE 


set item code 


40$: 


PUSHAL 

FILE 

; address of descriptor 

PUSHAL 

CODE 

; address of item code 

PUSHAL 

©CONTEXT(AP) 

; address of symbiont ctx value 

CALLS 

#3,G~PSM$READ_ITEM_DX 

; read it 

BLBC 

RO,40$ 

; branch if any errors 

he user 

name 


MOVZBL 

#SMBMSG$K_USER_NAME,CODE 

; set item code 

PUSHAL 

USER 

; address of descriptor 

PUSHAL 

CODE 

; address of item code 

PUSHAL 

©CONTEXT(AP) 

; address of symbiont ctx value 

CALLS 

#3.G~PSM$READ_ITEM_DX 

; read it 

BLBC 

RO,40$ 

; branch if any errors 

p the static header information that 

is constant for the task 

$FA0_S 

CTRSTR = FAO.CTRL, - 

; FAO control string desc 


OUTBUF = FAO.DESC, - 

; output buffer descriptor 


PI = #ACCOUNT, - 

; account name descriptor 


P2 = #USER, - 

; user name descriptor 


P3 = #FILE 

; file name descriptor 

RET 


; return success or any error 




(Continued on next page) 
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Example PSM-1 (Cont.) 


Using PSM Routines to Supply a Page 
Header Routine in a Macro Program 


Read a page header 


50$: 



DECL 

LINE 

; decrement the line number 

BEQL 

60$ 

; branch if second read 

BLSS 

70$ 

; branch if third read 

the page number into the header 


INCL 

PAGE 

; increment the page number 

MOVAB 

FAO.BUFF+76,FAO.DESC+4 

; point to page number buffer 

$FA0_S 

CTRSTR = FA0_CTRL_2, - 

; FAO control string desc 


0UTBUF = FAO.DESC, - 

; output buffer descriptor 


PI = PAGE 

; page number 

MOVAB 

FAO.BUFF,FAO.DESC+4 

; point to work buffer 

BLBC 

R0,55$ 

; return if error 


Copy the line to the symbiont's buffer 


55$: 


PUSHAB 

PUSHL 

CALLS 

RET 


FAO.DESC 
FUNC.DESC(AP) 

#2,G~STR$C0PY_DX 



Second line — underline header 


60$: 




PUSHL 

FUNC.DESC(AP) 


PUSHAL 

LINSIZ 


CALLS 

#2,G~STR$GET1_DX 


BLBC 

R0,67$ 


MOVL 

FUNC.DESC(AP),R1 


MOVL 

4(R1),R1 


MOVAB 

80(Rl),RO 

65$: 

MOVB 

#~A/-/.(Ri)+ 


CMPL 

R0,R1 


BGTRU 

65$ 


MOVB 

#10,(Rl)+ 

66$: 

MOVZBL 

#SS$_N0RMAL,RO 

67$: 

RET 



Done with this page header 
70$: 

MOVL #PSM$_E0F.R0 

MOVZBL #2,LINE 
RET 

.END START 


9.5 


PSM Routines 


work buffer descriptor 
symbiont descriptor 
copy to symbiont buffer 
return success or any error 


symbiont descriptor 

number of bytes to reserve 

reserve the space 

exit if error 

get address of descriptor 

get address of buffer 

set up transfer limit 

fill with dashes 

reached limit? 

branch if not 

extra line feed 

set success 

return 


return end of input 
reset line counter 
return 


The following pages describe the individual PSM routines in routine template 
format. 
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PSM$PRINT 



Invokes the VAX/VMS-supplied print symbiont. 

PSM$PRINT must be called exactly once after all user service 
routines have been specified using PSM$REPLACE. 

FORMAT 

PSM$PRINT [streams][,bufsiz][, worksiz] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

streams 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Maximum number of streams that the print symbiont is to support. The 
streams argument is the address of a longword containing this number, 
which must be in the range 2 to 26 . If streams is not specified, a default 
value of 2 is used. Thus, by default, a user-modified print symbiont supports 
one stream, which is to say that it is a single-threaded symbiont. 

A stream (or thread) is a logical link between a print execution queue 
and a printing device. When a symbiont process can accept simultaneous 
links to more than one queue, that is, when it can service multiple queues 
simultaneously, the symbiont is said to be multi-threaded. 

bufsiz 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Maximum buffer size in bytes that the print symbiont is to use for output 
operations. The bufsiz argument is the address of a longword containing the 
specified number of bytes. 

The print symbiont actually uses a buffer size that is the smaller of (1) the 
value specified by bufsiz and (2) the SYSGEN parameter MAXBUF. If bufsiz 
is not specified, then the print symbiont uses the value of MAXBUF. 

The print symbiont uses this size limit only for output operations. Output 
operations involve the placing of processed or formatted pages into a buffer 
that will be passed to the output routine. 
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The print symbiont uses the value specified by bufsiz only as an upper limit; 
most buffers that it writes will be smaller than this value. 

worksiz 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Size in bytes of a work area to be allocated for the use of user routines. The 
worksiz argument is the address of a longword containing this size in bytes. 

If worksiz is not specified, no work area is allocated. 

A separate area of the specified size is allocated for each active symbiont 
stream. 

DESCRIPTION 

The PSM$PRINT routine must be called exactly once after all user routines 
have been specified to the print symbiont. Each user routine is specified to 
the symbiont in a call to the PSM$REPLACE routine. 

The PSM$PRINT routine allows you to specify whether the print symbiont 
is to be single-threaded or multi-threaded, and if multi-threaded, how many 
streams or threads it can have. In addition, this routine allows you to control 
the maximum size of the output buffer. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

Any condition values returned by the $SETPRV, $GETSYI, $PURGWS, and 
$DCLAST system services. 

Any condition values returned by the SMB$INITIALIZE routine documented 
in Chapter 10. 
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PSM$READ_ITEM_DX 



Returns an item of information stored by the VAX/VMS print 
symbiont. These items of information are sent to the symbiont 
from the job controller. 

FORMAT 

PSM$READ_ITEM_DX request—id,item ,buffer 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

request—id 

VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Request identifier that was supplied by the symbiont to the user routine that 
is currently calling PSM$READ_ITEM_DX; the symbiont always supplies 
a request identifier when it calls a user routine with a service request. The 
request —id argument is the address of a longword containing this request 
identifier value. 

Your user routine must copy the request identifier value that the symbiont 
supplies (in the request_id argument) when it calls your user routine. Then, 
when your user routine calls PSM$READ_ITEM_DX, it must supply (in 
the request —id argument) the address of the request identifier value that it 
copied. 

item 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Item code that identifies the message-item that PSM$READ_ITEM_ DX is to 
return. The item argument is the address of a longword that specifies the 
item's code. 

For a complete list and description of each item code, refer to the 
documentation of the item argument in the SMB$READ_MESSAGE—ITEM 
routine in Chapter 10, Symbiont/Job-Controller Interface (SMB) Routines. 
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buffer 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Buffer into which PSM$READ_ITEM_DX returns the specified informational 
item. The buffer argument is the address of a descriptor pointing to this 
buffer. 


The PSM$READ_ITEM_DX routine returns the specified informational item 
by copying that item to the buffer using one of the STR$COPY_xx routines 
documented in the VAX/VMS Run-Time Library Routines Reference Manual. 


DESCRIPTION PSM$READ_ITEM_DX obtains the value of message items that are sent 

by the job controller and stored by the VAX/VMS symbiont. You use 
PSM$READ_ITEM_DX to obtain information about the task currently being 
processed, for example, the name of the file being printed (SMBMSG$K_ 
FILE—SPECIFICATION), or the name of the user who submitted the job 
(SMBMSG$K_USER_NAME). 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL Normal successful completion. 

PSM$_INVITMCOD The item argument specified an invalid item code. 

Any condition values returned by any of the STR$COPY_xx routines 
documented in the VAX/VMS Run-Time Library Routines Reference Manual. 
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PSM$REPLACE 



Substitutes a user service routine for a symbiont routine or adds a 
user service routine to the set of symbiont routines. 

You must call PSM$REPLACE once for each routine that you replace 
or add. 

FORMAT 

PSM$REPLACE code,routine 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

code 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Routine code that identifies a symbiont routine. The code argument is the 
address of a longword containing the routine code. 

Some routine codes identify routines that are supplied with the VAX/VMS 
symbiont; when you specify such a routine code, you replace the symbiont- 
supplied routine with your service routine. 

Two routine codes identify routines that are not supplied with the VAX/VMS 
symbiont; when you specify such a routine code, your service routine is 
added to the set of symbiont routines. 

Table PSM-1 lists each routine code in the order in which it is called within 
the symbiont execution stream; this table also specifies whether a routine code 
identifies an input, formatting, or output routine, and whether the routine is 
supplied with the VAX/VMS symbiont. 

The routine codes are defined by the $PSMDEF macro. The following lists 
each routine code in alphabetical order; the description of each code includes 
the following information about its corresponding routine: 

• Whether the routine is supplied by the VAX/VMS symbiont 

• Whether the routine is an input, formatting, or output routine 

• Under what conditions the routine is called 

• What task the routine performs 
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Routine Codes 
PSM$K_FILE_BURST 

This code identifies a symbiont-supplied input routine: it is called whenever 
a file burst page is requested. This routine obtains information about the job, 
formats the file burst page, and returns it to the input buffer. A file burst page 
follows a file flag page, and precedes the contents of the file. 

PSM$K_FILE_ERRORS 

This code identifies a symbiont-supplied input routine: it is called when 
errors have occurred during the job. This routine places the error message 
text in the input buffer. 

PSM$K_FILE_FLAG 

This code identifies a symbiont-supplied input routine: it is called whenever 
a file flag page is requested. This routine obtains information about the job, 
formats the file flag page, and returns it to the input buffer. A flag page 
follows the job burst page (if any), and precedes the file burst page (if any). It 
contains such information as the file specification of the file and the name of 
the user issuing the print request. 

PSM$K_FILE_IN FORMATION 

This code identifies a symbiont-supplied input routine: it is called when the 
file information item has been specified by the job controller. This routine 
expands the file information item to text and returns it to the input buffer. 

PSM$K_FILE_SETUP 

This code identifies a symbiont-supplied input routine: it is always called. 
This routine queues any specified file-setup modules for insertion, in the input 
stream, when the PSM$K_FILE—SETUP routine closes. 

PSM$K_FILE—SETUP—2 

This code identifies a symbiont-supplied input routine; it is always called. 
This routine returns a formfeed to ensure that printing of the file begins at the 
top of the page. This routine is called just before the main input routine. 

PSM$K_FILE—TRAILER 

This code identifies a symbiont-supplied input routine: it is called whenever 
a file trailer page is requested. This routine obtains information about the job, 
formats the file trailer page, and returns it to the input buffer. A trailer page 
follows the last page of the file contents. 

PSM$K_MAIN—FORMAT 

This code identifies the symbiont-supplied formatting routine: it is always 
called. This routine performs numerous formatting functions. You cannot 
replace this routine. 

PSM$K_FORM—SETUP 

This code identifies a symbiont-supplied input routine: it is always called. 
This routine queues any specified form-setup modules for insertion, in the 
input stream, when the PSM$K_FORM—SETUP routine closes. 
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PSM$K_INPUT_FILTER 

This code identifies a format routine that is not supplied by the VAX/VMS 
symbiont. If the routine is supplied by the user, it is always called, 
immediately prior to the symbiont-supplied formatting routine (routine 
code PSM$K_MAIN—FORMAT). An input-filter service routine is useful 
for modifying input data records and their carriage control before they are 
formatted by the symbiont. 

PSM$K_JOB—BURST 

This code identifies a symbiont-supplied input routine: it is called whenever 
a job burst page is requested. This routine obtains information about the job, 
formats the job burst page, and returns it to the input buffer. A job burst 
page follows the job flag page and precedes the file flag page (if any) of the 
first file in the job. It is similar to a file burst page except that it appears only 
once per job and only at the beginning of the job. 

PSM$K_JOB—COMPLETION 

This code identifies a symbiont-supplied input routine: it is always called. 
This routine returns a formfeed, which causes any output buffered by the 
device to be printed. 

PSM$K_JOB_FLAG 

This code identifies a symbiont-supplied input routine: it is called whenever 
a job flag page is requested. This routine obtains information about the job, 
formats the job flag page, and returns it to the input buffer. A job flag page is 
similar to a file flag page except that it appears only once per job, preceding 
the job burst page (if any). 

PSM$K_JOB_RESET 

This code identifies a symbiont-supplied input routine: it is always called. 
This routine queues any specified job-reset modules for insertion, in the input 
stream, when the PSM$K_JOB—RESET routine closes. 

PSM$K_JOB_SETUP 

This code identifies a symbiont-supplied input routine: it is always called. 
This routine checks to see if this is the first job to be printed on the device, 
and if so, it issues a formfeed and then performs a job reset. See the 
description of the PSM$K_JOB—RESET routine for information about job 
reset. 

PSM$K_JOB—TRAILER 

This code identifies a symbiont-supplied input routine: it is called whenever 
a job trailer page is requested. This routine obtains information about the job, 
formats the job trailer page, and returns it to the input buffer. A job trailer 
page is similar to a file trailer page except that it appears only once per job, as 
the last page in the job. 

PSM$K_MAIN—INPUT 

This code identifies a symbiont-supplied input routine: it is always called. 
This routine opens the file to be printed, returns input records to the input 
buffer, and closes the file. 
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PSM$K_LIBRARY_INPUT 

This code identifies a symbiont-supplied input routine; it is called when an 
input routine closes and when modules have been requested for insertion in 
the input stream. This routine returns the contents of the specified modules, 
one record per call. You cannot replace this routine. 

PSM$K_OUTPUT_FILTER 

This code identifies a formatting routine that is not supplied by the VAX /VMS 
symbiont. If the routine is supplied by the user, it is always called. This 
routine executes prior to the symbiont output routine (routine code 
PSM$K_OUTPUT). An output-filter service routine is useful for modifying 
output data buffers before they are passed to the output routine. 

At the point where the output-filter routine executes within the symbiont 
execution stream, the input data is no longer in record format; instead, the 
data exists as a stream of characters. The carriage control, for example, is 
embedded in the data stream. Thus, the output buffer may contain what was 
once a complete record, part of a record, or several records. 

PSM$K_PAGE_HEADER 

This code identifies a symbiont-supplied input routine; it is called once at the 
beginning of each page if page headers are requested. This routine returns to 
the input buffer one or more lines containing information about the file being 
printed and the current page number. This routine is called only while the 
main input routine is open. 

PSM$K_PAGE_SETUP 

This code identifies a symbiont-supplied routine; it is called at the beginning 
of each page if page-setup modules were specified. This routine queues any 
specified page-setup modules for insertion in the input stream when the 
PSM$K__PAGE—SETUP routine closes. This routine is called only while the 
main input routine is open. 

PSM$K_OUTPUT 

This code identifies the symbiont-supplied output routine: it is always called. 
This routine writes the contents of the output buffer to the printing device, 
but it also performs many other functions. 


routine 


VMS Usage: 
type: 
access: 
mechanism: 


procedure 

procedure entry mask 
read only 
by reference 


User service routine that is to replace a symbiont routine or to be included. 
The routine argument is the address of the user routine entry point. 


DESCRIPTION The routine codes that may be specified in the code argument are of two 

types: those that identify existing print symbiont routines and those that 
do not. All the routine codes are similar, however, in the sense that each 
supplies a location within the print symbiont execution stream where your 
routine can execute. 
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By selecting a routine code that identifies an existing symbiont routine, you 
effectively disable that symbiont routine. The service routine that you specify 
may perform the function that the disabled symbiont routine performs or it 
may not. If it does not, the net effect of the replacement is to eliminate that 
function from the list of functions performed by the print symbiont. Exactly 
what your service routine does is entirely up to you. 

By selecting a routine code that does not identify an existing symbiont routine 
(those that identify the input-filter and output-filter routines), your service 
routine has a chance to execute at the location signified by the routine code. 
Since the service routine you specify to execute at this location does not 
replace another symbiont routine, your service routine is an addition to the 
set of symbiont routines. 

As mentioned, each routine code identifies a location in the symbiont 
execution stream, whether or not it identifies a symbiont routine. Table 
PSM-1 lists each routine code in the order in which the location it identifies is 
reached within the symbiont execution stream. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 
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PSM$REPORT 



Reports to the print symbiont the completion status of an 
asynchronous operation that was initiated by a user routine. 

Such a user routine must have returned the completion status 
PSM$_PENDING. 

PSMSREPORT must be called exactly once for each time that a user 
routine has returned the status PSM$_PENDING. 

FORMAT 

PSMSREPORT requestsid [^status] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

request—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Request identifier that was supplied by the symbiont to the user routine at 
the time the symbiont called the user routine with the service request; the 
user routine must have returned the completion status PSM$_PENDING on 
the call for this service request. The request—id argument is the address of a 
longword containing the request identifier value. 

The symbiont calls the user routine with a request code that specifies the 
function that the symbiont expects the user routine to perform. In the call, 
the symbiont also supplies a request identifier, which serves to identify the 
request. If the user routine initiates an asynchronous operation, a mechanism 
is required for notifying the symbiont that the asynchronous operation has 
completed and for providing the completion status of the operation. 

The PSM$REPORT routine conveys the above two pieces of information. 

In addition, PSM$REPORT returns to the symbiont (in the request-id 
argument) the same request identifier value as that supplied by the symbiont 
to the user routine that initiated the operation. In this way, the symbiont 
synchronizes the completion status of an asynchronous operation with that 
invocation of the user routine that initiated the operation. 

Any user routine that initiates an asynchronous operation must, therefore, 
copy the request identifier value that the symbiont supplies (in the 
request—id argument) when it calls the user routine. The user routine will 
later need to supply this value to PSM$REPORT. 


PSM—31 











Print Symbiont Modification (PSM) Routines 

PSM$REPORT 


In addition, when the user routine returns, which it does before the 
asynchronous operation has completed, the user routine must return the 
status PSM$_PENDING. 


status 

VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by reference 


Completion status of the asynchronous operation that has completed. The 
status argument is the address of a longword containing this completion 
status. The status argument is optional; if it is not specified, the symbiont 
assumes the completion status SS$_NORMAL. 

The user routine that initiates the asynchronous operation must test for the 
completion of the operation and must supply the operation's completion 
status as the status argument to the PSM$REPORT routine. The Description 
section describes this procedure in greater detail. 

If the completion status specified by status has the low bit clear, the symbiont 
aborts the task. 


DESCRIPTION An asynchronous operation is an operation that, once initiated, executes "off 
to the side" and need not be completed before other operations can begin 
to execute. Asynchronous operations are common in symbiont applications 
because a symbiont, if it is multithreaded, must handle concurrent I/O 
operations. 

One example of a user routine that performs an asynchronous operation is 
an output routine that calls the $QIO system service to write a record to the 
printing device. When the user output routine completes execution, the I/O 
request queued by $QIO may not have completed. In order to synchronize 
this I/O request, that is, to associate the I/O request with the service request 
that initiated it, you should use the following mechanism: 

1 In making the call to $QIO, specify the astadr and iosb arguments. The 
astadr argument specifies an AST routine to execute when the queued 
output request has completed, and the iosb argument specifies an I/O 
status block to receive the completion status of the I/O operation. Item 
3 below describes some necessary functions that you will want your AST 
routine to do. 

2 Have the user output routine return the status PSM$_PENDING. 

3 Write the AST routine to perform the following functions: 

a Copy the completion status word from the I/O status block to a 
longword location that you will specify as the status argument in the 
call to PSM$REPORT. 

b Call PSM$REPORT. Specify as the request-id argument the request 
identifier that was supplied, by the print symbiont, in the original call 
to the user output routine. 


CONDITION SS$_NORMAL Normal successful completion. 

VALUES 

RETURNED 
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USER-FORMAT-ROUTINE 


Is a user-written routine that performs format operations. The 
symbiont's control logic routine calls your format routine at one of 
two possible points within the symbiont's execution stream. You 
select this point by specifying one of two routine codes when you 
call the PSM$REPLACE routine. 

A user format routine may be an input filter routine (routine code 
PSM$K_INPUT_FILTER) or an output filter routine (routine code 
PSM$K_OUTPUT_FILTER). The main format routine (routine code 
PSM$K_MAIN_FORMAT) may not be replaced. 

A user format routine must use the call interface described here. 


FORMAT USER-FORMAT-ROUTINE request-id,work_area 

,func ,func—desc— 1 
,func—arg _ 1 
,func—desc—2 
,func—arg—2 

The func_arg__ 1 and func_arg—2 arguments are not used in some cases; see 
the Description section for more information. 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. All utility routines return (by value) a condition 
value in RO. Condition values that can be returned by this routine are listed 


under "CONDITION VALUES RETURNED." 


ARGUMENTS 


request—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
write only 
by reference 


Request identifier that is supplied by the symbiont when it calls your format 
routine. The request_id argument is the address of a longword containing 
this request identifier value. 
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work—area 


VMS Usage: 
type: 
access: 
mechanism: 


address 

longword (unsigned) 
write only 
by reference 


Work area supplied by the symbiont for the use of your format routine; the 
symbiont supplies the address of this area when it calls your routine. The 
work—area argument is a longword containing the address of the work area 
The work area is a section of memory that your format routine can use for 
buffering and other internal operations. 

The size of the work area allocated is specified by the work—size argument 
in the PSM$PRINT routine. If work_size is not specified in the call to 
PSM$PRINT, no work area is allocated. 


In a multithreaded symbiont, a separate work area is allocated for each 
thread. This work area is shared by all user routines. The work area is 
initialized to zero when the symbiont is first started. 


func 

VMS Usage: 
type: 
access: 
mechanism: 


function _code 
longword (unsigned) 
write only 
by reference 


Function code specifying the service that the symbiont expects your format 
routine to perform. The func argument is the address of a longword into 
which the symbiont writes this function code. 


The function code specifies the reason why the symbiont is calling your 
format routine or, in other words, the service that the symbiont expects your 
routine to perform at this time. 

The PSM$K—FORMAT function code is the only function code to which your 
format routine must respond. When the symbiont calls your format routine 
with this function code, your routine must move a record from the input 
buffer to the output buffer. 

The symbiont may call your format routine with other function codes. 

Your routine should return the status PSM$_FUNNOTSUP (function not 
supported) when it is called with any of the following function codes or with 
any undocumented function code. 


The following function codes correspond to message items sent by the job 


controller to the symbiont; Section 
greater detail: 

PSM$K_ST ART—STREAM 
PSM$K_ST ART_T ASK 
PSM$K_RESUME_T ASK 
PSM$K_RESET_STREAM 


9.3.6, discusses these message items in 

PSM$K_STOP_STREAM 
PSM$K_PAUSE_T ASK 
PSM$K_STOP_TASK 


Other function codes correspond to internal symbiont mechanisms that are 
not part of the public interface to the print symbiont. 

In conclusion, your format routine should return the status 

PSM$_FUNNOTSUP or SS$_NORMAL when it is called with message 

function code or with a private function code. 
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func—desc _ 7 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Descriptor supplying an input record to be processed by the format routine. 
The func_desc_l argument is the address of a string descriptor. The 
symbiont supplies, by using this argument, the input record that your format 
routine is to process. Since this descriptor may be of any valid string type, 
it is recommended that your format routine use the Run-Time Library string 
routines to analyze this descriptor and manipulate the input record. 


func—arg _ 7 


VMS Usage: 
type: 
access: 
mechanism: 


vector_byte_unsigned 
byte (unsigned) 
read only 
by reference 


Carriage control for the input record supplied by func_desc_l. The 
func_arg_l argument is the address of a 4-byte vector that specifies the 
carriage control for the input record. The following diagram depicts the 
format of this 4-byte vector: 
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Bytes 0 and 1 describe the leading carriage control to apply to the input data 
record; bytes 2 and 3 describe the trailing carriage control. 

Byte 0 is a number specifying the number of times that the carriage control 
specifier in byte 1 is to be repeated preceding the input data record. Byte 2 is 
a number specifying the number of times that the carriage control specifier in 
byte 3 is to be repeated following the input data record. 

For values of the carriage control specifier from 1 to 255, the specifier is the 
ASCII character to be used as carriage control. Value 0 represents the ASCII 
"newline" sequence. Newline consists of a carriage return followed by a 
linefeed. 

The func_arg_l argument is not used if your format routine is an output 
filter routine (routine code PSM$K_OUTPUT_FILTER). See the Description 
section for more information. 
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func—desc—2 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by reference 


Descriptor of a buffer to which your format routine writes the formatted 
output record. The func—desc—2 argument is the address of a string 
descriptor. 

Your format routine must return the formatted data record by using the 
func_desc 2 argument. 

It is recommended that your format routine use the Run-Time Library string 
routines to write into the buffer specified by this descriptor. 


func—arg—2 


VMS Usage: 
type: 
access: 
mechanism: 


vector_byte_unsigned 
byte (unsigned) 
read only 
by reference 


Carriage control for the output record returned in func_desc_2. The 
func—arg—2 argument is the address of a 4-byte vector that specifies the 
carriage control for the output record. See the description of func_arg—1 for 
the contents and format of this 4-byte vector. 

If you do not process the carriage-control information supplied in 

func—arg—1 , then you should copy that value into func_arg_2. Otherwise, 

the carriage-control information will be lost. 

The func_arg_2 argument is not used if your format routine is an output 
filter routine (routine code PSM$K_OUTPUT_FILTER). See the Description 
section for more information. 


DESCRIPTION When used, the func—arg—1 argument describes carriage control information 

for the input data record, and the func_arg_2 describes carriage control 
information for the output data record. 

The input data record is passed to the format routine (input filter or output 
filter) for processing, and the output data record is returned by the format 
routine (input filter or output filter). 

One of the tasks performed by the main format routine (routine code 
PSM$K_MAIN—FORMAT) is that of embedding the carriage control 
information (specified by func—arg—1) into the data record (specified by 
func_desc_1). Thus, the output data (specified by func—desc—2) contains 
embedded carriage control and is therefore no longer in record format; it is, 
therefore, properly referred to as an output data stream rather than an output 
data record. 

Similarly, the output filter routine (routine code PSM$K_OUTPUT—FILTER), 
which executes after the main format routine, uses neither the func—arg_1 
nor func—arg—2 arguments; the data it receives (via func—desc_ 1) and the 
data it returns (via func—desc—2) are data streams, not data records. 
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However, the input filter routine (routine code PSM$K_INPUT_PILTER), 
which executes before the main format routine, uses both func_arg_l and 
func_arg__2. This is so because the main format routine has not yet executed, 
and so the carriage control information has not yet been embedded in the 
data record. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL Successful completion. The user format routine 

has completed the function that the symbiont 
requested. 

PSM$_FUNNOTSUP The user format routine does not support or does 

not recognize the function code supplied by the 
symbiont. To ensure future compatibility, your 
format routine should return this status for any 
unrecognized status codes. 

Any error condition values that you have coded your format routine to return. 

Refer to Section 9.3.2 for more information about error condition values. 
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USER-INPUT-ROUTINE 



Is a user-written routine that performs input operations. The 
symbiont calls your routine at a specified point in its execution 
stream; you specify this point using the PSM$REPLACE routine. 

FORMAT 

USER-1 NPUT-ROUTINE request—id, work—area 

,func ,funcdesc ,funcarg 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

request—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Request identifier value that is supplied by the symbiont when it calls your 
input routine. The request_id argument is the address of a longword 
containing this request identifier value. 

If your input routine initiates an asynchronous operation (for example, 
a call to the $QIO system service), your input routine must copy the 
request identifier value specified by request_id because this value must 
later be passed to the PSM$REPORT routine. See the description of the 
PSM$REPORT routine for more information. 

work—area 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Work area supplied by the symbiont for the use of your input routine; the 
symbiont supplies the address of this area when it calls your routine. The 
work_area argument is a longword into which the symbiont writes the 
address of the work area. The work area is a section of memory that your 
input routine can use for buffering and other internal operations. 

The size of the work area allocated is specified by the work—size argument 
in the PSM$PRINT routine. If work—size is not specified in the call to 
PSM$PRINT, no work area is allocated. 


PSM—38 












Print Symbiont Modification (PSM) Routines 

USER-INPUT-ROUTINE 


In a multithreaded symbiont, a separate work area is allocated for each 
thread. This work area is shared by all user routines. The work area is 
initialized to zero when the symbiont is first started. 


func 

VMS Usage: 
type: 
access: 
mechanism: 


function _code 
longword (unsigned) 
read only 
by reference 


Function code that is supplied by the symbiont when it calls your input 
routine. The func argument is the address of a longword containing this 
code. 


The function code specifies the reason why the symbiont is calling your 
input routine or, in other words, the function that the symbiont expects your 
routine to perform at this time. 

Most function codes require or allow additional information to be passed in 
the call by means of the funcdesc and funcarg arguments. The description of 
each input function code, therefore, includes a description of how these two 
arguments are used with that function code. 

The following lists all the function codes that the symbiont can specify when 
it calls your input routine (function codes applicable only to format and 
output routines are explained in the descriptions of the USER-FORMAT- 
ROUTINE and USER-OUTPUT-ROUTINE, respectively); all function codes 
are defined by the $PSMDEF macro. 


Function Codes for Input Routines 
PSM$K_CLOSE 

When the symbiont calls your routine with this function code, your routine 
must terminate processing by releasing any resources it may have allocated. 

The symbiont calls your routine with PSM$K —CLOSE when (1) your routine 
returns from a PSM$K_READ function call with the status PSM$_EOF 
(end of input) or with any error condition or (2) the symbiont receives a 
task-abortion request from the job controller. 

In any event, the symbiont will always call your input routine with 
PSM$K_CLOSE if your routine has returned successfully from a 
PSM$K_OPEN function call. This guaranteed behavior ensures that any 
resources your routine may have allocated on the OPEN will be released on 
the CLOSE. 


PSM$K_GET—KEY 

Typically, the use of both the PSM$K_GET—KEY and PSMK$K_POSITION_ 
TO—KEY function codes is appropriate only for a main input routine (routine 
code PSM$K_MAIN-INPUT). 

When the symbiont calls your routine with this function code, your routine 
may do one of two things: (1) return PSM$_FUNNOTSUP (function not 
supported) or (2) return an input marker string to the symbiont. 

If your routine returns PSM$_FUNNOTSUP to this function code, then your 
routine must also return PSM$_FUNNOTSUP if the symbiont subsequently 
calls your routine with the PSM$K_POSITION—TO_KEY function code. By 
returning PSM$_FUNNOTSUP, your routine is choosing not to respond to 
the symbiont request. 
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If your routine chooses to respond to the PSM$K_GET_KEY function code, 
your routine must return an input marker string to the symbiont; this input 
marker string identifies the input record that your input routine most recently 
returned to the symbiont. Subsequently, when the symbiont calls your input 
routine with the PSM$K_POSITION—TO_KEY function code, the symbiont 
will pass your input routine one of the input marker strings that your input 
routine has returned on a previous PSM$K_GET_KEY function call. Using 
this marker string, your input routine must position itself so that, on the next 
PSM$K_READ call from the symbiont, your input routine will return (or 
reread) the input record identified by the marker string. 

Coding your input routine to respond to PSM$K_GET—KEY and PSM$K_ 
POSITION—TO—KEY allows the modified symbiont to perform the file 
positioning functions specified by the DCL commands START/QUEUE 
/FORWARD, START/QUEUE/ALIGN, START/QUEUE/TOP—OF_FILE, 
START/QUEUE/SEARCH, and START/QUEUE/BACKWARD, and by the 
job controller's checkpointing capability for print jobs. 

Note that your input routine might be called with a marker string that was 
originally returned in a different process context from the current one. This 
can occur because marker strings are sometimes stored in the queue-data file 
across system shutdowns or different invocations of your symbiont. 

The funcdesc argument specifies the address of a string descriptor. Your 
routine must return the marker string via this argument. It is recommended 
that you use one of the Run-Time Library string routines to copy the marker 
string to the descriptor. 

The symbiont periodically calls your input routine with the 
PSM$K_GET—KEY function code, when the symbiont wishes to save a 
marker to a particular input record. 

PSM$K—OPEN 

When the symbiont calls your routine with this function code, your routine 
should prepare for input operations by performing such tasks as allocation of 
necessary resources, initialization of storage areas, opening of an input file, 
and so on. Typically, the next time the symbiont calls your input routine, 
the symbiont will specify the PSM$K_READ function code. Note, however, 
that under some circumstances the symbiont might follow an OPEN call 
immediately with a CLOSE call. 

The funcdesc argument points to the name of the file to be opened. Your 
routine can use this file specification or the file identifcation to open the file. 

The funcarg argument specifies the address of a longword. Your input 
routine must return, in this longword, the carriage control type that is to be 
applied to the input records that your input routine will provide. 

The symbiont formatting routine requires this information to determine where 
to apply leading and trailing carriage control characters to the input records 
that your input routine will provide. 

The $PSMDEF macro defines the following four carriage control types. 
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Carriage Type 

Description 

PSM$K_CC_IMPLIED 

Implied carriage control. For this type, the symbiont 
inserts a leading linefeed (If) and trailing carriage 
return (CR) in each input record. This is the default 
carriage control type; it is used if your routine does 
not supply a carriage control type in the funcarg 
argument in response to the PSM$K_OPEN function 
call. 

PSM$K_CC_FORTRAN 

FORTRAN carriage control. For this type, the 
symbiont extracts the first byte of each input record 
and interprets the byte as a FORTRAN carriage 
control character, which it then applies to the input 
record. 

PSM$K_CC_PRINT 

PRN carriage control. For this type, the symbiont 
generates carriage control from a two-byte record 
header that your input routine supplies, with each 
READ call, in the funcarg argument. The funcarg 
argument specifies the address of a longword to 
receive this two-byte header record, which appears 
only in PRN print files. 

PSM$K_CC_INTERNAL 

Embedded carriage control. For this type, the 
symbiont supplies no carriage control to input 
records. Carriage control is assumed to be embedded 
in the input records. 

PSM$K_POSITION_ 

-TO—KEY 


When the symbiont calls your routine with this function code, your routine 
must locate the point in the input stream designated by the marker string that 
your routine returned to the symbiont on the PSM$K_GET_KEY function 
call. 

The next time the symbiont calls your routine, the symbiont will specify the 
PSM$K_READ function call, expecting to receive the next sequential input 
record. After rereading this record, subsequent READ calls proceed from this 
new position of the file. This is not a one-time rereading of a single record, 
but a repositioning of the file. 

The symbiont calls your routine with this function code when the job 
controller receives a request to resume printing at a particular page. 

Refer to the description of the PSM$K_GET__KEY for more information. 

PSM$K_READ 

When the symbiont calls your routine with this function code, your routine 
must return an input record. 

The symbiont repeatedly calls your input routine with the PSM$K_READ 
function code until either (1) your routine indicates end of input by returning 
the status PSM$_EOF, (2) your routine or another routine returns an error 
status, or (3) the symbiont receives an asynchronous task-abortion request 
from the job controller. 

The funcdesc argument specifies the address of a string descriptor. 

Your routine must return the input record by using this argument. It is 
recommended that you use one of the Run-Time Library string routines to 
copy the input record to the descriptor. 
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The funcarg argument specifies the address of a longword. This argument 
is used only if the carriage control type returned by your input routine on 
the PSM$K_OPEN function call was PSM$K_CC_PRINT. In this case, your 
input routine must supply, in the funcarg argument, the two-byte record 
header found at the beginning of each input record. 

PSM$K_REWIND 

When the symbiont calls your routine with this function code, your routine 
may do one of two things: (1) return PSM$_FUNNOTSUP (function not 
supported) or (2) must locate the point in the input stream designated as the 
beginning of the file. 

If your routine returns PSM$_FUNNOTSUP to this function code, then the 
symbiont will subsequently call your input routine with a 
PSM$K_CLOSE function call followed by a PSM$K_OPEN function call. By 
returning PSM$K_FUNNOTSUP, your routine is choosing not to support the 
repositioning of the input service to the beginning of the file. The symbiont, 
therefore, performs the desired function by closing and, then, reopenning of 
the input routine. 

The funcdesc and the funcarg arguments are not used with this function 
code. 

This function call allows the modified symbiont to perform the file positioning 
functions specified by the DCL commands START/QUEUE/TOP_OF__FILE, 
START/QUEUE/FORWARD, START/QUEUE/BACKWARD, START/QUEUE 
/SEARCH, and START/QUEUE/ALIGN. This is a required repositioning of 
the file. 

Other Input Function Codes 

The symbiont may call your input routine with other function codes. Your 
routine must return the status PSM$_FUNNOTSUP (function not supported) 
when it is called with any of the following function codes or with any 
undocumented function code. 

The following function codes correspond to message items sent by the job 
controller to the symbiont; Section 9.3.6 discusses these message items in 
depth: 

PSM$K_ST ART_STRE AM PSM$K_STOP_STREAM 

PSM$K_ST ART_T ASK PSM$K_PAUSE_TASK 

PSM$K _RESUME _T ASK PSM$K_STOP_TASK 

PSM$K_RESET_STREAM 

Other function codes correspond to internal symbiont mechanisms that are 
not part of the public interface to the print symbiont. 

In conclusion, your input routine should return the status 
PSM$K_FUNNOTSUP or SS$_NORMAL when it is called with a message 
function code or with a private function code. 
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funcdesc 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Function descriptor supplying information related to the function specified by 
the func argument. The funcdesc argument is the address of this descriptor. 

The contents of the function descriptor varies for each function. Refer to the 
description of each function code to determine the contents of the function 
descriptor. In some cases, the function descriptor is not used at all. 


funcarg 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Function argument supplying information related to the function specified 
by the func argument. The funcarg argument is the address of a longword 
containing this function argument. This argument can be an input or an 
output argument depending on the function request, but is usually used as an 
output argument. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL Successful completion. The user input routine 

has completed the function that the symbiont 
requested. 

PSM$_FLUSH The user input routine requests that the symbiont 

flush the output stream. The user input routine 
can only return this status when called with the 
PSM$K_READ function code. When this status 
is returned to the symbiont, the symbiont stops 
calling the input routine with the PSM$K_READ 
function code until all outstanding format and 
output operations have completed. 

PSM$_FUNNOTSUP The user input routine does not support or does 

not recognize the function code supplied by the 
symbiont. To ensure future compatibility, your 
input routine should return this status for any 
unrecognized status codes. 

PSM$_PENDING The user input routine has accepted but has 

not completed the requested function. Your 
input routine may return this status only with 
the PSM$K_READ function call. Further, if 
your routine returns PSM$_PENDING, your 
routine must eventually signal completion via 
the PSM$REPORT routine. Refer to the description 
of the PSM$REPORT routine for more information 
about asynchronous operations and the 
PSM$_PENDING condition value. 

Any error condition values that you have coded your format routine to return. 

Refer to Section 9.3.2 for more information about error condition values. 
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USER-OUTPUT-ROUTINE 



Is a user-written routine that performs output operations. You 
supply a user output routine by calling the PSM$REPLACE routine 
with the routine code PSM$K_OUTPUT. 

FORMAT 

USER-OUTPUT-ROUTINE request—id,work—area 

,func ,funcdesc ,funcarg 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

request—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Request identifier value that is supplied by the symbiont when it calls your 
output routine. The request_id argument is the address of a longword 
containing this value. 

If your output routine initiates an asynchronous operation (for example, a 
call to the Queue I/O Request (SYS$QIO) system service), you must save the 
request—id argument because you will need to store the request identifier 
value for later use with the PSM$REPORT routine. See the description of the 
PSM$REPORT routine for more information. 

work—area 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Work area supplied by the symbiont for the use of your format routine; the 
symbiont supplies the address of this area when it calls your routine. The 
work—area argument is a longword containing the address of the work area. 
The work area is a section of memory that your format routine can use for 
buffering and other internal operations. 

The size of the work area allocated is specified by the work—size argument 
in the PSM$PRINT routine. If work—size is not specified in the call to 
PSM$PRINT, no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each 
thread. This work area is shared by all user routines. The work area is 
initialized to zero when the symbiont is first started. 


func 

VMS Usage: 
type: 
access: 
mechanism: 


function_code 
longword (unsigned) 
read only 
by reference 


Function code that is supplied by the symbiont when it calls your output 
routine. The func argument is the address of a longword containing this 
code. 


The function code specifies the reason why the symbiont is calling your 
output routine or, in other words, the function that the symbiont expects your 
routine to perform at this time. 

Most function codes require or allow additional information to be passed in 
the call via the funcdesc and funcarg arguments. The description of each 
output function code, therefore, includes a description of how these two 
arguments are used for that function code. 

The following lists all the function codes that the symbiont may supply when 
it calls your output routine (function codes applicable only to input and 
formatting routines are explained in the descriptions of the user input routine 
and user formatting routine, respectively); all function codes are defined by 
the $PSMDEF macro. 


Function Codes for Output Routines 
PSM$K_OPEN 

When the symbiont calls your output routine with this function code, your 
routine should prepare to move data to the device by performing such tasks 
as allocating the device, assigning a channel to the device, and so on. The 
next time the symbiont calls your output routine, the symbiont will specify 
one of the WRITE function codes (PSM$K_WRITE or 
PSM$K_WRITE—NOFORMAT). 

The symbiont calls your output routine with the PSM$K_OPEN function 
code when the symbiont receives the SMBMSG$K_START_STREAM 
message from the job controller. 

If your output routine returns an error condition value (low bit clear) to 
the PSM$K_OPEN function call, the job controller stops processing on the 
stream and reports the error to the user that issued the DCL command 
START/QUEUE. 

The funcdesc argument is the address of a descriptor that identifies the name 
of the device that the output routine is to write to. This device name is 
established by the DCL command INITIALIZE/QUEUE/ON=device-name. 

The funcarg argument is the address of a longword into which the user 
output routine returns the device status longword. For the contents of the 
device status longword, refer to the description of the 

SMBMSG$K_DE VICE-STATUS item in the SMB$RE AD-MESS AGE-ITEM 
routine, which is documented in Section 9, Symbiont/Job-Controller Interface 
(SMB) Routines. 
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Your output routine sets bits in the device status longword to indicate the 
following to the job controller: 

• Whether the device can print lowercase letters 

• Whether the device is a terminal 

• Whether the device is connected to the CPU by means of a modem 
(remote) 

If your output routine does not set any of these bits in the device status 
longword, the job controller assumes, by default, that the device is a 
lineprinter that prints only uppercase letters. 

PSM$K_WRITE 

When the symbiont calls your routine with this function code, your routine 
must write data to the device. The symbiont supplies the data to be written 
in the funcdesc argument. It is recommended that you use one of the 
Run-Time Library string routines to access the data in the buffer described by 
the funcdesc argument. 

PSM$K_WRITE_NOFORMAT 

When the symbiont calls your routine with this function code, your routine 
must write data to the device and must indicate to the device driver that the 
data is not to be formatted. 

The symbiont calls your routine with this function code when (1) the print 
request specifies the PASSALL option or (2) data is introduced by the ANSI 
DCS (device control string) escape sequence. 

The symbiont supplies the data to be written in the funcdesc argument. It 
is recommended that you use one of the Run-Time Library string routines to 
move the data from the descriptor to the device. 

The output routine of the symbiont informs the device driver not to format 
the data in the following way: 

• When the device is a lineprinter, the symbiont's output routine specifies 
the IO$_WRITEPBLK function code when it calls the $QIO system service. 

• When the device is a terminal, the symbiont's output routine specifies 
the IO$M_NOFORMAT function modifier when it calls the $QIO system 
serivce. 

PSM$K_CANCEL 

When the symbiont calls your routine with this function code, your routine 
must abort any outstanding asynchronous I/O requests. 

The output routine supplied by the symbiont aborts outstanding I/O requests 
by calling the $QIO system service with the IO$_CANCEL function code. 

If your output routine returned the condition value PSM$_PENDING to 
one or more previous write requests that are still outstanding (that is, 
PSM$REPORT has not yet been called to report completion), then your 
output routine must call PSM$REPORT one time for each outstanding 
write request that is canceled with this call. That is to say, canceling an 
asynchronous write request does not relieve the user output routine of the 
requirement to call PSM$REPORT once for each asynchronous write request. 

The funcdesc and funcarg arguments are not used. 
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PSM$K_CLOSE 

When the symbiont calls your routine with this function code, your output 
routine must terminate processing and release any resources it allocated (for 
example, channels assigned to the device). 

The funcdesc and funcarg arguments are not used. 

Other Output Function Codes 

The symbiont may call your output routine with other function codes. 

Your routine should return the status PSM$_FUNNOTSUP (function not 
supported) when it is called with any of the following function codes or with 
any undocumented function code. 

The following function codes correspond to message items sent by the job 
controller to the symbiont; Section 10.2 discusses these message items in 
depth: 

PSM$K_ST ART_STREAM PSM$K_STOP_STREAM 

PSM$K_START_TASK PSM$K_PAUSE_TASK 

PSM$K_RESUME_T ASK PSM$K_STOP_TASK 

PSM$K_RESET_STREAM 


Other function codes correspond to internal symbiont mechanisms that are 
not part of the public interface to the print symbiont. 

In conclusion, your output routine should return the status 
PSM$K_FUNNOTSUP or SS$_NORMAL when it is called with a message 
function code or with a private function code. 


funcdesc 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Function descriptor supplying information related to the function specified by 
the func argument. The funcdesc argument is the address of this descriptor. 

The contents of the function descriptor vary for each function. Refer to the 
description of each function code to determine the contents of the function 
descriptor. In some cases, the function descriptor is not used at all. 


funcarg 

VMS Usage: 
type: 
access: 
mechanism: 


user_arg 

longword (unsigned) 
read only 
by reference 


Function argument supplying information related to the function specified 
by the func argument. The funcarg argument is the address of a longword 
containing this function argument. 

The contents of the function argument vary for each function. Refer to the 
description of each function code to determine the contents of the function 
argument. In some cases, the function argument is not used at all. 
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CONDITION SS$_NORMAL 

VALUES 

RETURNED psm$_funnotsup 


PSM$_PENDING 


Successful completion. The user output routine 
has completed the function that the symbiont 
requested. 

The user output routine does not support or does 
not recognize the function code supplied by the 
symbiont. To ensure future compatibility, your 
output routine should return this status for any 
unrecognized status codes. 

The user output routine has accepted but has not 
completed the requested function. Your output 
routine may return this status only with 
PSM$K_WRITE and PSM$K_WRITE_NOFORMAT 
function calls. Further, if your routine returns 
PSM$_PENDING, your routine must eventually 
signal completion via the PSM$REPORT routine. 
Refer to the description of the PSM$REPORT 
routine for more information about asynchronous 
write operations and the PSM$_PENDING condition 
value. 


Any error condition values that you have coded your output routine to return. 
Refer to Section 9.3.2 for more information about error condition values. 
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10 Symbiont/Job Controller Interface (SMB) 
Routines 


10.1 Introduction to SMB Routines 

The SMB routines provide the interface between the job controller and 
symbiont processes. A user-written symbiont must use these routines to 
communicate with the VAX/VMS job controller. 

Always use the SMB interface routines or SYS$SNDJBC system service to 
communicate with the job controller. You do not need to, and should not 
attempt to, communicate directly with the job controller. 

To write a symbiont of your own it is useful to understand how symbionts 
work and, in particular, how the standard VAX/VMS print symbiont behaves. 


10.1.1 Types of Symbionts 

There are two types of symbionts: 

• Device symbiont, either an input symbiont or an output symbiont. An 
input symbiont is a symbiont that transfers data from a slow device to 
a fast device, for example, from a card reader to a disk. A card-reader 
symbiont is an input symbiont. An output symbiont is a symbiont that 
transfers data from a fast device to a slow device, for example, from a disk 
to a printer or terminal. A print symbiont is an output symbiont. 

• Server symbiont, a symbiont that processes or transfers data but is not 
associated with a particular device; one example is a symbiont that 
transfers files across a network. 

The VAX/VMS operating system does not supply any server symbionts. 


10.1.2 Symbionts Supplied with the VAX/VMS Operating System 

The VAX/VMS operating system supplies two symbionts: 

• SYS$SYSTEM:PRTSMB.EXE (PRTSMB for short), an output symbiont for 
use with printers and printing terminals. 

PRTSMB performs such functions as inserting flag, burst, and trailer pages 
into the output stream; reading and formatting input files; and writing 
formatted pages to the printing device. 

You can modify PRTSMB using the Print-Symbiont-Modification (PSM) 
routines. 

• SYS$SYSTEM:INPSMB.EXE (INPSMB for short) an input symbiont for use 
with card readers. 

This symbiont handles the transferring of data from a card reader to a disk 
file. 
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You cannot modify INPSMB. Nor can you write an input symbiont using 
the SMB routines. 


10.1.3 Symbiont Behavior in the VAX/VMS Environment 

In the VAX/VMS environment, a symbiont is a process under the control of 
the VAX/VMS job controller that transfers or processes data. 

Figure SMB-1 depicts the VAX/VMS components that take part in the 
handling of user requests that involve symbionts. This figure shows two 
symbionts: (1) the VAX/VMS operating system-supplied print symbiont, 
PRTSMB and (2) a user-written symbiont, GRAPHICS.EXE, which services a 
graphics plotter. The numbers that appear in the figure refer to the activities 
listed below the figure. 

This list does not reflect the activities that must be performed by the 
hypothetical, user-written symbiont, GRAPHICS.EXE. This symbiont is 
represented in the figure to illustrate the correspondence between a user- 
written symbiont and the VAX/VMS operating system-supplied print 
symbiont. 

Although SMB routines can be used for a different kind of symbiont, many 
of their arguments and associated symbols have names that are related to 
the print symbiont. The print symbiont is presented here as an example of a 
typical symbiont, and illustrates points that are generally true for symbionts. 
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Figure SMB-1 Symbionts in the VAX/VMS Operating System 
Environment 
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O You request a printing job with the DCLs PRINT command. DCL calls 
the Send to Job Controller (SYS$SNDJBC) system service, passing the 
name of the file to be printed to the job controller, along with any other 
information specified by qualifiers for the PRINT command. 

© The job controller places the print request in the appropriate queue and 
assigns the request a job number. 

© The job controller breaks the print job into a number of tasks (for example, 
printing three copies of the same file is three separate tasks). The job 
controller makes a separate request to the symbiont for each task. 

Each request that the job controller makes consists of a message. Each 
message consists of a code that indicates what the symbiont is to do, and 
a number of items of information that the symbiont needs to carry out the 
task (the name of the file, the name of the user, and so on.) 

O PRTSMB interprets the information it receives from the job controller. 
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© PRTSMB locates and opens the file it is to print by using the file- 

identification number the job controller specified in the start-task message. 

© PRTSMB sends the data from the file to the printer's driver. 

© The device driver sends the data to the printer, which prints it. 


10.1.4 Why Write a Symbiont? 

Writing your own symbiont permits you to use the queueing mechanisms and 
control functions of the VAX/VMS job controller. You might want to do this 
if you need a symbiont for a device that cannot be served by PRTSMB (or a 
modified form of PRTSMB), or if you need a server symbiont. The interface 
between the job controller and the symbiont permits the symbiont you write 
to use the many features of the job controller. 

For example, when you use DCL PRINT command to print a file, the job 
controller sends to the print symbiont a message that tells it to print a file. 

When a user-written symbiont receives the same message, however, (caused 
by a user typing a PRINT command), it might interpret it to mean something 
quite different. A robot symbiont, for example, might interpret the message 
as a command for movement and the file specification (specified with the 
PRINT command) might be a file describing the directions in which the robot 
is to move. 

Note: Modifying PRTSMB is easier than writing your own symbiont; choose 
this option if possible. The Print Symbiont Modification (PSM) routines 
describe how to modify PRTSMB to suit your needs. 


10.1.5 Guidelines for Writing a Symbiont 

Although you can write a symbiont to use the queuing mechanisms and other 
features of the job controller in whatever way you want, you must follow 
these guidelines to ensure that your symbiont works correctly: 

• The symbiont must not use any of the process-permanent channels, which 
are assigned to the logical names: 

• SYS$INPUT 

• SYS$OUTPUT 

• SYS$ERROR 

• SYS$COMMAND 

• The symbiont must allocate and deallocate memory using the RTL routines 
LIB$GET_VM and LIB$FREE_VM. 

• To be compatible with future releases of the VAX/VMS operating system, 
the symbiont should be written to ignore unknown message-item codes 
and unknown message-request codes. (See the SMB$READ_ITEM_ 
MESSAGE routine.) 

• The symbiont must communicate with the job controller by using the 
Job-Controller/Symbiont Interface (SMB) routines and the $SNDJBC 
system service. 
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• The symbiont can receive messages only from the job controller when it 
is not executing within the context of an AST routine. It is recommended 
that the symbiont not perform lengthy operations within the context of an 
AST routine. 

• To assign a symbiont to a queue once it has been compiled and linked, 
the executable image of the symbiont must reside in SYS$SYSTEM, and 
either of the following commands must be issued: 

$ INITIALIZE/QUEUE/PROCESSOR*symbiont_file_name 
$ START/QUEUE/PROCESSOR*symbiont_file_name 

You should specify only the file name in the command. The disk and 
directory default to SYS$SYSTEM, and all fields except the file name are 
ignored. 


10.1.6 The Symbiont/Job-Controller Interface Routines 

The five SMB routines form a public interface to the VAX/VMS job controller. 
The job controller delivers requests to symbionts by means of this interface, 
and the symbionts communicate their responses to those requests through this 
interface. A user-written symbiont uses the following routines to exchange 
messages with the job controller: 

SMBSINITIALIZE Initializes the SMB facility's internal database, 

establishes the interface to the job controller, 
and defines whether: 

1 Messages from the job controller are to be 
delivered to the symbiont synchronously or 
asynchronously with respect to execution 
of the symbiont 

2 The symbiont is to be single-threaded 
or multithreaded; these concepts are 
described below 


SMB$CHECK_FOR_MESSAGE 

SMB$READ_MESSAGE 

SMB$READ_MESSAGE_ITEM 

SMB$SEND_TO_I0BCTL 


Checks to see if a message from the job 
controller to the symbiont has arrived 

Reads the job controller's message into a 
buffer 

Returns one item of information from the job 
controller's message (which can have several 
informational items) 

Sends a message from the symbiont to the 
job controller 


The remaining sections of this introduction discuss how to use the SMB 
routines when writing your symbiont. 


10.1.7 Choosing the Symbiont Environment 

The first SMB routine that a symbiont must call is the SMB$INITIALIZE 
routine. In addition to allocating and initializing the SMB facility's internal 
database, it offers you two options for your symbiont environment: 
synchronous or asynchonous delivery of messages from the job controller, 
and single streaming or multistreaming the symbiont. 
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10.1.7.1 Synchronous Versus Asynchronous Delivery of Requests 

When you initialize your job controller/symbiont interface, the symbiont 
has the option of accepting requests from the job controller sychronously or 
asynchronously. 

Synchronous Environment 

The address of an AST routine is an optional argument to the 
SMB$INITIALIZE routine; if it is not specified, the symbiont receives 
messages from the job controller synchronously. A symbiont that receives 
messages synchronously must call SMB$CHECK_FOR—MESSAGE 
periodically during the processing of tasks in order to ensure the timely 
delivery of STOP-TASK, PAUSE-TASK, and RESET-STREAM requests. 

SMB$CHECK_FOR—MESSAGE checks to see if a message from the job 
controller is waiting. If a message is waiting, SMB$CHECK_FOR—MESSAGE 
returns a success code. The caller of SMB$CHECK_FOR—MESSAGE can 
then call SMB$READ_MESSAGE to read the message and take appropriate 
action. 

If no message is waiting, SMB$CHECK_FOR—MESSAGE returns a zero in 
RO. The caller of SMB$CHECK_FOR—MESSAGE can continue to process the 
task at hand. 

Figure SMB-2 is a flowchart for a synchronous, single-threaded symbiont. 
The flowchart does not show all the details of the logic the symbiont needs, 
and does not show how the symbiont handles pause-task, resume-task, or 
reset-stream requests. Figure SMB-3 is a flowchart for an asynchronous, 
single-threaded symbiont. 
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Figure SMB-2 Flowchart for a Single-Threaded, Synchronous Symbiont 


SYNCHRONOUS, SINGLE-THREADED SYMBIONT 
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Asynchronous Environment 

To receive messages asynchronously, a symbiont specifies a message-handling 
AST routine as the second argument to the SMB$INITIALIZE routine. In this 
scheme, whenever the job controller sends messages to the symbiont, the 
AST routine is called. 
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The AST routine is called with no arguments and returns no value. You have 
the option of having the AST routine read the message within the context of 
its execution, or of having the AST routine wake a suspended process to read 
the message outside the context of the execution of the AST routine. 

Be aware that an AST can be delivered only while the symbiont is not 
executing within the context of an AST routine. Thus, in order to ensure 
delivery of messages from the job controller, the symbiont should not perform 
lengthy operations at AST level. 

This is particularly important to the execution of STOP-TASK, 

PAUSE-TASK, and RESET-STREAM requests. If a STOP-TASK request 
cannot be delivered during the processing of a task, for example, it is useless. 

One technique that ensures delivery of STOP and PAUSE requests in an 
asynchronous environment is to have the AST routine set a flag if it reads a 
PAUSE-TASK, STOP-TASK, or a RESET-STREAM request, and to have the 
symbiont's main routine periodically check the flag. 

The following figure is a logic chart for a single-threaded, asynchronous 
symbiont. The figure does not show many details that your symbiont might 
include, such as a call to the $QIO system service. 

Note that the broken lines that connect the calls to SYS$HIBER with the 
AST routine's calls to SYS$WAKE show that the next action to take place is 
the call to SYS$WAKE. They do not accurately represent the flow of control 
within the symbiont, but represent the action of the job controller in causing 
the AST routine to execute. 
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Figure SMB-3 Flow Chart for a Single-Threaded, Asynchronous 

Symbiont 


ASYNCHRONOUS. SINGLE-THREADED SYMBIONT 
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Figure SMB-3 (Cont.) Flow Chart for a Single-Threaded, 

Asynchronous Symbiont 
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10.1.7.2 Single Streaming Versus Multistreaming 

A stream (or thread) is a logical link between a queue and a symbiont process. 
When a symbiont process is linked to more than one queue, it can serve those 
queues simultaneously, and is called a multithreaded symbiont. 

The argument to the SMB$READ_MESSAGE routine provides a way for a 
multithreaded symbiont to keep track of the stream to which a request refers. 
Writing your own multi threaded symbiont, however, can be a complex 
undertaking. 


10.1.8 Reading Job Controller Requests 

There are seven general functions that the job controller can request of the 
symbiont: 

SMBMSG$K_ST ART_STRE AM SMBMSG$K_STOP_STREAM 

SMBMSG$K_ST ART_T ASK SMBMSG$K_PAUSE_T ASK 

SMBMSG$K_RESUME_T ASK SMBMSG$K_STOP_TASK 

SMBMSG$K_RESET_STREAM 

The job controller passes the symbiont these requests in a structure that 
contains (1) a code that identifies the requested function and (2) (optional) 
items of information that the symbiont might need to perform the requested 
function. 

By calling SMB$READ_MESSAGE, the symbiont reads the function code 
and writes the associated items of information, if any, into a buffer. The 
symbiont then parses the message-items stored in the buffer by calling the 
SMB$RE AD_MESS AGE _ITEM routine. SMB$RE AD-MESS AGE-ITEM 
reads one message-item each time it is called. 

Each message-item consists of a code that identifies the type of information 
the item contains, and the information itself. For example, the 
SMB$K_JOB—NAME code tells the symbiont that the item contains a string, 
the name of a job. 

The number of message-items in a request message varies with each type of 
request. Therefore, SMB$READ_MESSAGE—ITEM must be called repeatedly 
for each request to ensure that all message-items are read. 

SMB$RE AD-MESS AGE-ITEM returns status SMB$_NOMOREITEMS after 
it has read the last message-item in a given request. 

Typically, a symbiont checks the code of a message-item against a case 
table and stores the message string in an appropriate variable until all the 
message-items are read and the processing of the request can begin. 

See the description of the SMB$READ_MESSAGE—ITEM routine for a table 
that shows the message-items that make up each type of request. 
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10.1.9 Processing Job Controller Requests 

Once a request has been read it must be processed. The way a request is 
processed depends on the type of request. The following section lists, for 
each request that the job controller sends to the print symbiont, the actions 
that the standard symbiont (PRTSMB) takes when the message is received. 
These actions are oriented toward print symbionts in particular but can serve 
as a guideline for other kinds of symbionts as well. 

The symbiont you write can respond to requests in a similar way or in a 
different way appropriate to the function of your symbiont. We suggest that 
your routines follow the guidelines described in this document. (Note that 
the behavior of the standard symbiont is subject to change without notice in 
future versions of the VAX/VMS operating system.) 

SMBMSG$K_START_STREAM 

• Reset all stream-specific information that might have been altered by 
previous START-STREAM requests on this stream (for multithreaded 
symbionts). 

• Read and store the message-items associated with the request. 

• Allocate the device specified by the SMBMSG$K_DEVICE—NAME item. 

• Assign a channel to the device. 

• Obtain the device characteristics. 

• If the device is neither a terminal nor a printer, then abort processing and 
return an error to the job controller by means of the 

SMB$SEND_TO—JOBCTL routine. Note that even though an error has 
occurred, the stream is still considered to be started. The job controller 
detects the error and sends a STOP—STREAM request to the symbiont. 

• Set temporary device characteristics suited to the way the device will be 
used by the symbiont. 

• For remote devices (devices connected to the system by means of a 
modem) establish an AST to report loss of the carrier signal. 

• Report to the job controller that the request has been completed, and that 
the stream is started, by specifying SMBMSG$K_START—STREAM in the 
call to SMB$SEND_TO—JOBCTL. 

SMBMSG$K_START—TASK 

• Reset all task-specific information that might have been altered by 
previous START—TASK requests on this stream number. 

• Read and store the message-items associated with the request. 

• Open the main input file. 

• Report to the job controller that the task has been started by specifying 
SMBSMG$K_START—TASK in the call to the SMB$SEND_TO_JOBCTL 
routine. 

• Begin processing the task. 

• When the task is complete, notify the job controller by specifying 
SMBMSG$K_TASK—COMPLETE in the call to the 
SMB$SEND_TO—JOBCTL routine. 
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SMBMSG$K_PAUSE_TASK 

• Read and store the message-items associated with the request. 

• Set a flag that will cause the main processing routine to pause at the 
beginning of the next output page. 

• When the main routine has paused, notify the job controller by specifying 
SMBMSG$K_PAUSE_TASK in the call to the 
SMB$SEND_TO_JOBCTL routine. 

SMBMSG$K_RESUME_TASK 

• Read and store the message-items associated with the request. 

• Perform any positioning functions specified by the message-items. 

• Clear the flag that causes the main input routine to pause, and resume 
processing the task. 

• Notify the job controller that the task has been resumed by specifying 
SMBMSG$K_RESUME_TASK in the call to the 
SMB$SEND_TO_ JOBCTL routine. 

SMBMSG$K_STOP_TASK 

• Read and store the message-items associated with the request. 

• If processing of the current task has paused, then resume it. 

• Cancel any outstanding I/O operations. 

• Close the input file. 

• If the job controller specified, in the START_TASK message, that a trailer 
page be printed when the task is stopped, or if it specified that the device 
should be reset when the task is stopped, then perform those functions. 

• Notify the job controller that the task has been stopped abnormally by 
specifying SMBMSG$K_STOP_TASK, and by specifying an error vector in 
the call to SMB$SEND_TO_JOBCTL. PRTSMB specifies the value passed 
by the job controller in the SMBMSG$K_STOP_CONDITION item as the 
error condition in the error vector. 

SMBMSG$K_STOP_STREAM 

• Read and store the message-items associated with the request. 

• Release any stream-specific resources; (1) deassign the channel to the 
device, (2) deallocate the device. 

• Notify the job controller that the stream has been stopped by specifying 
SMBMSG$K_STOP_STREAM in the call to SMB$SEND_TO_JOBCTL. 

• If this is a single-threaded symbiont, or if this is a multi threaded symbiont 
but all other streams are currently stopped, then call the SYS$EXIT system 
service with the condition code SS$_NORMAL. 
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SMBMSG$K_RESET_STREAM 

• Read and store the message-items associated with the request. 

• Abort any task that is in progress—it is not necessary to notify the job 
controller that the task has been aborted, but you can do so if you wish. 

• If the job controller specified, in the START-TASK message, that a trailer 
page be printed when the task is stopped, or if it specified that the device 
should be reset when the task is stopped, then suppress those functions. 

The job controller sends the symbiont a RESET—STREAM request to regain 
control of a queue or a device that has failed to respond to a STOP—TASK 
request. The RESET—STREAM request should avoid any further I/O 
activity if possible. The printer might be disabled, for example, and 
requests for output on that device will never be completed. 

• Continue as if this were a STOP—STREAM request. 

Note: A STOP—STREAM request and a RESET—STREAM request each stops 

the queue; but a RESET—STREAM request is an emergency stop, uses, for 
example, when the device has failed. A RESET—STREAM request should 
prevent any further I/O activity because the printer might not be able to 
complete it. 


10.1.10 Responding to Job Controller Requests 

The symbiont uses the SMB$SEND_TO_JOBCTL routine to send messages 
to the job controller. 

Most messages that the symbiont sends to the job controller are responses to 
requests made by the job controller. Such messages inform the job controller 
that the request has been completed, successfully or unsuccessfully. The 
function code that the symbiont returns to the controller in the call to 
SMB$SEND_TO—JOBCTL indicates what request has been completed. 

For example, if the job controller sends a START—TASK request using 
the SMBMSG$K_START—TASK code, the symbiont responds by calling 
SMB$SEND_TO—JOBCTL using SMBMSG$K_START—TASK as the request 
argument to indicate that task processing has begun. Until the symbiont 
responds, the DCL SHOW QUEUE command indicates that the queue is 
starting. 

The responses to some requests use additional arguments to send more 
information than just the request code. See the SMB$SEND_TO_JOBCTL 
routine for a table showing the additional arguments allowed in response to 
each request. 

In addition to sending messages in response to requests, the symbiont can 
send other messages to the job controller. In these messages the symbiont 
sends either the SMBMSG$K_TASK— COMPLETE code, indicating that it 
has completed a task, or SMBMSG$K_TASK—STATUS, indicating that the 
message contains information on the status of a task. 

Note that when a START—TASK request is delivered, the symbiont responds 
with a SMB$SEND_TO—JOBCTL message with the SMBSMG$K-START- 
TASK code. This response means that the task has been started. It does not 
mean the task has been completed. When the symbiont completes the task, 
it calls SMB$SEND_TO—JOBCTL with the SMBSMG$K—TASK—COMPLETE 
code. 
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10.2 SMB Routines 

The following pages describe the individual SMB routines in routine template 
format. 


SMB-15 






Symbiont/Job Controller Interface (SMB) Routines 

SMB$CHECK_FOR_MESSAGE 


SMB$CHECK_FOR—MESSAGE 



Determines whether a message sent from the job controller to the 
symbiont is waiting to be read. 

FORMAT 

SMB$CHECK_FOR_MESSAGE 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

None. 

DESCRIPTION 

When your symbiont calls the SMB$INITIALIZE routine to initialize the 
interface between the symbiont and the job controller, you can choose to 
have requests from the job controller be delivered by means of an AST. If 
you choose not to use ASTs, your symbiont must call SMB$CHECK—FOR— 
MESSAGE during the processing of tasks in order to see if a message from the 
job controller is waiting to be read. If a message is waiting, SMB$CHECK_ 
FOR—MESSAGE returns a success code; if not, it returns a zero. 

If a message is waiting, the symbiont should call SMB$READ_MESSAGE to 
read it and determine if immediate action should be taken (as in the case of 
STOP-TASK, RESET-STREAM or PAUSE-TASK). 

If a message is not waiting, SMB$CHECK_MESSAGE returns a zero. If this 
condition is detected, the symbiont should continue processing the request at 
hand. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL One or more messages are waiting 

0 No messages are waiting 
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SMB$IIMITIALIZE 



Initializes the user-written symbiont and the interface between 
the symbiont and the job controller. It allocates and initializes the 
internal databases of the interface and sets up the mechanism which 
will wake up symbiont when a message is received. 

FORMAT 

SMB$INITIALIZE structure—le\/el[,ast— routine] 

[,streams] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

structure—level 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Version of the job-controller/symbiont interface. The structure—level 
argument is the address of a longword that contains the version of the 
job-con troller/symbiont interface that was used when the symbiont was 
compiled. Always place the value of the symbol 

SMBMSG$K_STRUCTURE—LEVEL in the longword addressed by this 
argument. This symbol is defined by the $SMBDEF macro. The $SMBDEF 
macro is defined in the macro library SYS$LIBRARY:LIB.MLB. 

ast—routine 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

Message-handling routine called at AST level. The AST—routine is the 
address of the entry point of the message-handling routine to be called at 
AST level when the symbiont receives a message from the job controller. The 
AST routine is called with no parameters and returns no value. If an AST 
routine is specified, the routine is called once each time the symbiont receives 
a message from the job controller. 

The AST routine typically reads the message and determines if immediate 
action must be taken. Be aware that an AST can only be delivered while the 
symbiont is operating at non-AST level. Thus, in order to ensure delivery of 
messages from the job controller, the symbiont should not perform lengthy 
operations at AST level. 
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The AST_routine argument is optional. If it is not specified the symbiont 
must call the SMB$CHECK_FOR_MESSAGE routine to check for waiting 
messages. 


streams 

VMS Usage: 
type: 
access: 
mechanism: 


longword_unsigned 
longword (unsigned) 
read only 
by reference 


Maximum number of streams that the symbiont will support. The streams 
argument is the address of a longword that contains the number of streams 
that the symbiont will support. The number must be in the range 1 to 16 . 

If this argument is not specified, a default value of 1 is used. Thus, by default, 
a symbiont supports one stream. Such a symbiont is called a single-threaded 
symbiont. 

A stream (or thread) is a logical link between a queue and a symbiont. When 
a symbiont is linked to more than one queue, it can serve those queues 
simultaneously, and is called a multi threaded symbiont. 


DESCRIPTION Your symbiont must call SMB$INITIALIZE before calling any other SMB$ 

routines. It calls SMB$INITIALIZE in order to: 

• Allocate and initialize the SMB$ facility's internal database. 

• Establish the interface between the job controller and the symbiont. 

• Determine the threading scheme of the symbiont. 

• Set up the mechanism which will wake your symbiont when a message is 
received. 

Once the symbiont calls SMB$INITIALIZE, it can communicate with the job 
controller using the other SMB$ services. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL Routine successfully completed 

SMB$_INVSTRLEV Invalid structure level 

Any codes returned by $ ASSIGN and LIB$GET_VM. 
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SM B$RE AD_M ESS AGE 



Copies a message that the job controller has sent into the caller's 
specified buffer. 

FORMAT 

SMB$READ_MESSAGE stream ,buffer,request 

RETURNS 

VMS Usage: cond_.value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

stream 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Stream number specifying the stream to which the message refers. The 
stream argument is the address of a longword into which the job controller 
writes the number of the stream to which the message refers. In single- 
threaded symbionts the stream number is always 0. 

buffer 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Message. The buffer argument is the address of a descriptor that points to 
the buffer into which the job controller writes the message. 
SMB$READ_MESSAGE uses the RTL STR$ string-handling routines to copy 
the message into the buffer you supply. It is recommended that the buffer be 
specified by a dynamic string-descriptor. 

request 

VMS Usage: identifier 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

The address of a longword into which SMB$READ_MESSAGE writes the 
code that identifies the request. 
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There are seven request codes. Each code is interpreted as a message by the 
symbiont. The codes and their corresponding messages follow: 


SMBMSG$K_ST ART_STRE AM 


SMBMSG$K_STOP_STREAM 


SMBMSG$K_RESET_STREAM 


SMBMSG$K_ST ART_T ASK 


SMBMSG$K_ST OP_T ASK 


SMBMSG$K_PAUSE_T ASK 


SMBMSG$K_RESUME_TASK 


Initiates processing on an inactive symbiont 
stream. The job controller sends this message 
when a START/QUEUE or an INITIALIZE 
/QUEUE/START command is issued on a 
stopped queue. 

Stops processing on a started queue. The job 
controller sends this message when a STOP 
/QUEUE/NEXT command is issued, after the 
symbiont completes any currently active task. 

Aborts all processing on a started stream and 
requeues the current job. The job controller 
sends this message when a STOP/QUEUE 
/RESET command is issued. 

Requests that the symbiont begin processing 
a task. The job controller sends this message 
when a file is pending on an idle, started 
queue. 

Requests that the symbiont abort the 
processing of a task. The job controller sends 
this message when a STOP/QUEUE/ABORT or 
STOP/QUEUE/REQUEUE command is issued. 
The item SMBMSG$K_STOP_CONDITION 
identifies whether this is an abort or a requeue 
request. 

Requests that the symbiont pause in the 
processing of a task but retain the resources 
necessary to continue. The job controller 
sends this message when a STOP/QUEUE 
command is issued without the /ABORT, 
/ENTRY, /REQUEUE, or /NEXT qualifiers for a 
queue that is currently printing a job. 

Requests that the symbiont continue 
processing a task that has been stopped 
with a PAUSE-TASK request. This message 
is sent when a START/QUEUE command is 
issued for a queue served by a symbiont that 
has paused in processing the current task. 


DESCRIPTION Your symbiont calls SMB$READ_MESSAGE to read a message that the job 

controller has sent to the symbiont. 

Each message from the job controller consists of a code that identifies the 
function the symbiont is to perform and a number of message-items. There 
are seven codes. Message-items are pieces of information that the symbiont 
needs to carry out the requested function. 

For example, when you issue DCL's PRINT command, the job controller 
sends a message that contains a START-TASK code and a message-item that 
contains the specification of the file to be printed. 

SMB$READ_MESSAGE writes the code into a longword (specified by the 
request argument) and writes the accompanying message-items, if any, into a 
buffer (specified by the buffer argument). 


SMB-20 



Symbiont/Job Controller Interface (SMB) Routines 

SMB$READ_MESSAGE 



See the description of the SMB$READ_MESSAGE_ITEM routine for 
information on processing the individual message-items. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine completed successfully 

LIB$_INVARG Routine completed unsuccessfully due to an invalid 

argument 

Any of the condition codes returned by the Run-Time Library string-handling 
(STR$) routines. 
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SMB$READ_MESSAGE_ITEM 



Performs the following activities: 

1 Reads a buffer that was filled by the SMB$READ_MESSAGE 
routine. 

2 Parses one message-item from the buffer. 

3 Writes the item's code into a longword. 

4 Writes the item into a buffer. 

FORMAT 

SMB$READ_MESSAGE_ITEM message,context 

, item—code, buffer 
[ r size] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return (by value) a condition 
value in RO. Condition values that can be returned by this routine are listed 
under "CONDITION VALUES RETURNED." 

ARGUMENTS 

message 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Message items that SMB$READ-MESSAGE—ITEM is to read. The message 
argument is the address of a descriptor of a buffer. The buffer is the one that 
contains the message-items that SMB$READ_MESSAGE—ITEM is to read. 
The buffer specified here must be the same as that specified with the call to 
the SMB$READ_MESSAGE routine, which fills the buffer with the contents 
of the message. 

context 

VMS Usage: context 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

A value initalized to 0 specifying the first message item in the buffer to 
be read. The context argument is the address of a longword that the 
SMB$READ_MESSAGE—ITEM routine uses to determine the next message- 
item to be returned. When this value is 0 , it indicates that 

SMB$READ_MESSAGE—ITEM is to return the first message-item. 
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The SMB$READ_MESSAGE_JTEM routine updates this value each time it 
reads a message-item. SMB$READ_MESSAGE_ITEM sets the value to 0 
when it has returned all the message-items in the buffer. 


item—code 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Item code specified in the message item that identifies the type of message 
item. The item_code argument is the address of a longword into which 
SMB$READ__MESSAGE _ITEM writes the code that identifies what item it is 
returning. 

The codes that identify message-items are defined at the end of the 
Description section for this routine. The following diagram depicts the 
format of a single message item: 
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SMB$READ_MESSAGE _ITEM copies the code from the second word in the 
message-item to the longword specified by the item—code argument. 

SMB$READ_MESSAGE—ITEM uses the item-size field in the message-item 
to determine the length, in bytes, of the variable-length message. 


buffer 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Message item. The buffer argument is the address of a descriptor of a buffer. 
The buffer is the one in which the SMB$READ_MESSAGE—ITEM routine 
is to place the message-item. SMB$READ_MESSAGE—ITEM uses the RTL 
STR$ string-handling routines to copy the message-item into the buffer. 
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size 

VMS Usage: 
type: 
access: 
mechanism: 


word—unsigned 
word (unsigned) 
write only 
by reference 


Size of the message item. The size argument is the address of a word in 
which the SMB$READ_MESSAGE—ITEM is to place the size, in bytes, of the 
item. 


DESCRIPTION There are seven functions that the job controller can request of the symbiont. 

They are identified by the following codes: 

SMBMSG$K_ST ART-STREAM SMBMSG$K_STOP_STREAM 

SMBMSG$K_ST ART_T ASK SMBMSG$K_PAUSE_T ASK 

SMBMSG$K_RESUME_TASK SMBMSG$K_STOP_TASK 

SMBMSG$K_RESET_STREAM 

The job controller passes the symbiont a request that contains a code and, 
optionally, a number of message-items that contain information that the 
symbiont might need to perform the function. The code specifies what 
function the request is for, and the message-items contain information that 
the symbiont needs to cany out the function. 

By calling SMB$READ_MESSAGE, the symbiont reads the request and writes 
the message-items into the specified buffer. The symbiont then obtains 
the individual message-items by calling the SMB$READ_MESSAGE—ITEM 
routine. 

Each message-item consists of a code that identifies the information the item 
represents, and the item itself. For example, the SMB$K_JOB—NAME code 
tells the symbiont that the item specifies a job's name. 

The number of items in a request varies with each type of request. Therefore, 
SMB$READ_MESSAGE—ITEM must be called repeatedly for each request to 
ensure that all message-items are read. Each time SMB$READ_MESSAGE- 
ITEM reads a message-item, it updates the value in the longword specified 
by the context argument. SMB$READ—MESSAGE—ITEM returns the code 
SMB$_NOMOREITEMS after it has read the last message-item. 

The following list shows the message-items that can be delivered with each 
request: 


REQUEST message-item 

SMBMSG$K_ST ART_T ASK SMBMSG$K_ACCOUNT_NAME 

SMBMSG$K_AFTER_TIME 

SMBMSG$K_BOTTOM—MARGIN 

SMBMSG$K_CHARACTERISTICS 

SMBMSG$K_CHECKPOINT_DAT A 

SMBMSG$K_ENTRY_NUMBER 

SMBMSG$K_FILE_COPIES 

SMBMSG$K_FILE_COUNT 
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REQUEST 


SMBMSG$K_STOP_T ASK 
SMBMSG$K_PAUSE_T ASK 
SMBMSG$K_RESUME_TASK 


SMBMSG$K_ST ART_STRE AM 


SMBMSG$K_STOP_STREAM 

SMBMSG$K_RESET_STREAM 


message-item 

SMBMSG$K_SETUP_MODULES 

SMBMSG$K_FIRST_PAGE 

SMBMSG$K_FORM_LENGTH 

SMBMSG$K_FORM_NAME 

SMBMSG$K_FORM_SETUP_MODULES 

SMBMSG$K_FORM_WIDTH 

SMBMSG$K_FILE_IDENTIFICATION 

SMBMSG$K_MESSAGE_VECTOR 

SMBMSG$K_FILE_SPECIFICATION 

SMBMSG$K_JOB_COPIES 

SMBMSG$K_JOB_COUNT 

SMBMSG$K_JOB_NAME 

SMBMSGSK_IOB_RESET_MODULES 

SMBMSG$K_LAST_PAGE 

SMBMSG$K_LEFT_MARGIN 

SMBMSG$K_NOTE 

SMBMSG$K_PAGE_SETUP_MODULES 

SMBMSG$K_PARAMETER_1 

SMBMSG$K_SEPARATION_CONTROL 

SMBMSG$K_REQUEST_CONTROL 

SMBMSG$K_PRIORITY 

SMBMSG$K_QUEUE 

SMBMSG$K_TIME_QUEUED 

SMBMSG$K_TOP_MARGIN 

SMBMSG$K_UIC 

SMBMSG$K_USER_NAME 

SMBMSG$K_RIGHT_MARGIN 

SMBMSG$K_STOP_CONDITION 

None 

SMBMSG$K_ALIGNMENT_PAGES 

SMBMSG$K_RELATIVE_PAGE 

SMBMSGSK _REQUEST_CONTROL 

SMBMSG$K_SEARCH_STRING 

SMBMSG$K_DEVICE_NAME 

SMBMSG$K_EXECUTOR_QUEUE 

SMBMSG$K_JOB_RESET_MODULES 

SMBMSG$K_LIBRARY_SPECIFICATION 

None 

None 
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The following table shows the message-items that the symbiont can send to 
the job controller: 

• SMBMSG$K -ACCOUNTING -DATA 

• SMBMSG$K_CHECKPOINT—DATA 

• SMBMSG$K_CONDITION—VECTOR 

• SMBMSG$K_DE VICE-STATUS 

• SMBMSG$K_REQUEST—RESPONSE 

The following list enumerates each item-code. For each code, the list 
describes the contents of the message-item identified by the code and whether 
the code identifies an item sent from the job controller to the symbiont or 
from the symbiont to the job controller. 

Many of the codes described below are specifically oriented toward print 
symbionts. The symbiont you implement, which might not print files or serve 
an output device, need not recognize all these codes. In addition, it need not 
respond in the same way as the VAX/VMS print symbiont to the codes it 
recognizes. The descriptions in the list describe how the standard VAX/VMS 
print symbiont (PRTSMB.EXE) processes these items. 

Note: Since new codes might be added in the future, you should write your 
symbiont so that it ignores codes it does not recognize. 

Codes for Message-Items 
SMBMSG$K_ACCOUNTING—DATA 

This code identifies a 16-byte structure that the symbiont sends to the job 
controller. This structure contains accounting statistics that the symbiont has 
accumulated for the task. The job controller accumulates task statistics into a 
job-accounting record, which it writes to the accounting file when the job is 
completed. 

The following diagram depicts the contents of the 16-byte structure: 

3 

1 0 


NUMBER OF PAGES PRINTED FOR THE JOB 


NUMBER OF READS FROM DISK 


NUMBER OF WRITES TO THE PRINTING DEVICE 


UNUSED 
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SMBMSG$K—ACCOUNT—NAME 

This code identifies a string that contains the name of the account to be 
charged for the job, the account of the process that submitted the print job. 
The job controller sends this item to the symbiont. 
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SMBMSG$K_AFTER_TIME 

This code identifies a 64-bit, absolute-time value that specifies the system 
time after which the job controller can process this job. The job controller 
sends this item to the symbiont. 

SMBMSG$K_ALIGNMENT_PAGES 

This code identifies a longword that specifies the number of alignment 
pages that the symbiont is to print. The job controller sends this item to the 
symbiont. 

SMBMSG$K_BOTTOM—MARGIN 

This code identifies a longword that contains the number of lines that are to 
be left blank at the bottom of a page. The job controller sends this item to 
the symbiont. 

If the symbiont determines that: 

1 The number of lines left at the bottom of the page is equal to this value 

2 Sending more data to the printer to be output on this page would cause 
characters to be printed within this bottom margin of the page, and 

3 The /FEED qualifier was specified with the PRINT command that caused 
the symbiont to perform this task, 

then the symbiont inserts a formfeed character into the output stream. 
(Linefeed, formfeed, carriage-return, and vertical-tab characters in the output 
stream are collectively known as embedded carriage control.) 

SMBMSG$K_CHARACTERISTICS 

This code identifies a 32-byte structure that specifies characteristics of the 
job. A detailed description of the format of this structure is contained in the 
description of the SJC$_CHARACTERISTIC code in the SYS$SNDJBC system 
service in the VAX/VMS System Services Reference Manual . The job controller 
sends this item to the symbiont. 

SMBMSG$K_CHECKPOINT-DATA 

This code identifies a user-defined structure that contains checkpointing 
information. The symbiont sends this item to the job controller, which saves 
it in the queue's data file. 

When a restart-from-checkpoint request is executed for the queue, the job 
controller retrieves the checkpointing information from the queue's data file 
and sends it to the symbiont with a SMBMSG$K_START—TASK request. The 
symbiont uses the checkpointing information to reposition the input file to 
the point corresponding to the last page output at the time of the checkpoint. 

SMBMSGSK—CONDITION—VECTOR 

This code identifies an array of longwords, each longword containing a code 
that specifies a termination status for the current request. The symbiont sends 
this item to the job controller. For example, the STS and STV values from an 
RMS control block might be two longwords in the array. 

SMBMSG$K_DEVICE—NAME 

This code identifies a string that is the name of the device to which the 
symbiont is to send data. The symbiont interprets this information. The 
name need not be the name of a physical device, and the symbiont can 
interpret this string as something other than the name of a device. 
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SMBMSG$K_DEVICE_STATUS 

This code identifies a longword bit-vector, each bit of which specifies device¬ 
status information. The symbiont sends this item to the job controller. The 
$SMBDEF macro defines these device-status bits. The following describes the 
effect of setting each bit in the longword. 


Device Status Bit 

SMBMSG$V_LOWERCASE 

SMBMSG$V_PAUSE_T ASK 

SMBMSG$V_REMOTE 

SMBMSG$V_SERVER 
SMBMSG$ V_ST ALLED 
SMBMSG$ V_ST OR_STRE AM 

SMBMSG$V_TERMINAL 
SMBMSG$V_UN AVAILABLE 


Description 

The device to which the symbiont is connected 
supports lowercase characters. 

Informs the job controller that the symbiont has 
paused on its own initiative. 

The device is connected to the symbiont by 
means of a modem. 

The symbiont is not connected to a device. 
Symbiont processing is temporarily stalled. 

The symbiont requests that the job controller 
stop the queue. 

The symbiont is connected to a terminal. 

The device to which the symbiont is assigned is 
not available. 


SMBMSG$K_ENTRY_NUMBER 

This code identifies a longword that contains the number that the job 
controller assigned to the job. The job controller sends this item to the 
symbiont. 

SMBMSG$K_EXECUTOR_QUEUE 

This code identifies a string that is the name of the queue on which the 
currently executing job is listed. The job controller sends this item to the 
symbiont. 

SMBMSG$K__FILE_COPIES 

This code identifies a longword that contains the number of copies of the file 
that were requested. 

SMBMSG$K-FILE_COUNT 

This code identifies a longword that specifies, out of the number of copies 
requested for this job (SMBMSG$K_FILE—COPIES), the number of the 
copy of the file currently printing. The job controller sends this item to the 
symbiont. 

SMBMSG$K_FILE—IDENTIFICATION 

This code identifies a 28-byte structure that identifies the file to be processed. 
This structure consists of the following three file-identification fields in the 
RMS NAM block: 

• The 16-byte NAM$T_DVI field 

• The 6-byte NAM$W_FID field 

• The 6-byte NAM$W_DID field 
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SMBMSG$K_FILE _SETUP_MODULES 

This code identifies a string that specifies the names of one or more text 
modules that the symbiont should copy from the library into the output 
stream before processing the file. When more than one name is given, 
commas separate them. The job controller sends this item to the symbiont. 

SMBMSG$K_FILE_SPECIFICATION 

This code identifies a string that specifies the name of the file that the 
symbiont is to process. This file name is formatted as a standard RMS file 
specification. The job controller sends this item to the symbiont. 

SMBMSG$K_FIRST_PAGE 

This code identifies a longword that contains the number of the page at which 
the symbiont should begin printing. The job controller sends this item to the 
symbiont. When not specified, the symbiont begins processing at page 1. 

SMBMSG$K_FORM_LENGTH 

This code identifies a longword value specifying the length (in lines) of the 
physical form (the paper). The job controller sends this item to the symbiont. 

SMBMSG$K_FORM_NAME 

This code identifies a string that specifies the name of the form. The job 
controller sends this item to the symbiont. 

SMBMSG$K__FORM_SETUP_MODULES 

This code identifies a string that consists of the names of one or more 
modules that the symbiont should copy from the device-control library 
before processing the file. When more than one name is given, commas must 
separate them. The job controller sends this item to the symbiont. 

SMBMSG$K_FORM_WIDTH 

This code identifies a longword that specifies the width (in characters) of the 
print-area on the physical form (the paper). The symbiont sends this item to 
the job controller. 

SMBMSG$K^JOB_COPIES 

This code identifies a longword that specifies the number of copies of the job 
that were requested. The job controller sends this item to the symbiont. 

SMBMSG$K_JOB_COUNT 

This code identifies a longword that specifies, out of the number of copies 
requested (SMBMSG$K_JOB_COPIES), the number of the copy of the job 
currently printing. The job controller sends this item to the symbiont. 

SMBMSG$K_JOB_NAME 

This code identifies a string that specifies the name of the job. The job 
controller sends this item to the symbiont. 

SMBMSG$K^JOB_RESET_MODULES 

This code identifies a string that specifies the names of one or more modules 
that the symbiont should copy from the device-control library after processing 
the task. These modules can be used to reset programmable devices to a 
known state. When more than one name is given, commas must separate 
them. The job controller sends this item to the symbiont. 
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SMBMSG$K_LAST_PAGE 

This code identifies a longword that specifies the number of the last page that 
the symbiont is to print. The job controller sends this item to the symbiont. 
When not specified, the symbiont attempts to print all the pages in the file. 

SMBMSG$K_LEFT_MARGIN 

This code identifies a longword that specifies the number of spaces to be 
inserted at the beginning of each line. The job controller sends this item to 
the symbiont. 

SMBMSG$K__LIBRARY_SPECIFICATION 

This code identifies a string that specifies the name of the device-control 
library. The job controller sends this item to the symbiont. 

SMBMSG$K_MESSAGE_VECTOR 

This code identifies a vector of longword condition-codes, each of which 
contains information about the job to be printed. The job controller sends 
this item to the symbiont. 

When LOGINOUT cannot open a log file for a batch job, a code in the 
message vector specifies the reason for the failure. The job controller does 
not send the SMBMSG$K_FILE —IDENTIFICATION item if it has detected 
such a failure, but instead sends the message vector, which the symbiont 
prints, along with a message stating that there is no file to print. 

SMBMSG$K_NOTE 

This code identifies a user-supplied string that the symbiont is to print on the 
job-flag page and on the file-flag page. The job controller sends this item to 
the symbiont. 

SMBMSG$K_PAGE_SETUP_MODULES 

This code identifies a string that consists of the names of one or more modules 
that the symbiont should copy from the device-control library before printing 
each page. When more than one name is given, commas must separate them. 
The job controller sends this item to the symbiont. 

SMBMSG$K_PARAMETER_1 through SMBMSG$K_PARAMETER_8 

Each of these eight codes identifies a user-supplied string. Both the semantics 
and syntax of each string are determined by your symbiont. The VAX/VMS- 
supplied symbiont makes no use of these eight items. The job controller 
sends these items to the symbiont. 

SMBMSG$K_PRINT_CONTROL 

This code identifies a longword bit-vector, each bit of which supplies 
information that the symbiont is to use in controlling the printing of the 
file. The job controller sends this item to the symbiont. 

The $SMBDEF macro defines the following symbols for each bit in the 
bit-vector: 
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Symbol 

Description 

SMBMSGS V_DOUBLE -SPACE 

When specified, the symbiont uses a double¬ 
spaced format; it skips a line after each line it 
prints. 

SMBMSG$V_NORECORD_ 

BLOCKING 

When specified, the symbiont performs single 
record output, issuing a single output record for 
each input record. 

SMBMSGS V_PAGE_HEADER 

When specified, the symbiont prints a page 
header at the top of each page. 

SMBMSG$V_P AGIN ATE 

When specified, the symbiont inserts a 
formfeed character when it detects an attempt 
to print in the bottom margin of the current 
form. 

SMBMSG$V_PASSALL 

When specified, the symbiont prints the file 
without formatting. The symbiont bypasses all 
formatting normally performed. Furthermore, 
the symbiont outputs the file without formatting 
by causing the output QIO to suppress 
formatting by the driver. 

SMBMSGS V_RECORD_ 
BLOCKING 

When specified, the symbiont performs record 
blocking, buffering output to the device. 

SMBMSG$V_SEQUENCED 

This bit is reserved to DIGITAL. 

SMBMSG$V_SHEET_FEED 

When specified, the symbiont pauses after each 
page that it prints. 

SMBMSG$V_TRUNCATE 

When specified, the symbiont truncates input 
lines that exceed the right margin of the current 
form. 

SMBMSGSV—WRAP 

When specified, the symbiont wraps input 
lines that exceed the right margin, printing the 
additional characters on a new line. 


SMBMSG$K_PRIORITY 

This code identifies a longword that specifies the priority that this job has 
in the queue in which it is entered. The job controller sends this item to the 
symbiont. 

SMBMSG$K_QUEUE 

This code identifies a string that specifies the name of the queue in which 
this job is entered. The job controller sends this item to the symbiont. When 
generic queues are used, this item specifies the name of the generic queue, 
and the SMBMSG$K_EXECUTOR item specifies the name of the device 
queue or the server queue. 

SMBMSG$K__RELATIVE_PAGE 

This code identifies a signed, longword value that specifies the number of 
pages that the symbiont is to move forward (positive value) or backward 
(negative value) from the current position in the file. The job controller sends 
this item to the symbiont. 

SMBMSG$K_REQUEST_CONTROL 

This code identifies a longword bit-vector, each bit of which specifies 
information that the symbiont is to use in processing the request that the 
job controller is making. The job controller sends this item to the symbiont. 
The $SMBDEF macro defines the following symbols for each bit: 
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Symbol Description 

SMBMSG$V_ALIGNMENT_MASK When specified, the symbiont is to replace 

all alphabetic characters with the letter "X", 
and all numeric characters with the number 
"9". Other characters (punctuation, carriage 
control, and so on) are left unchanged. This 
bit is ordinarily specified in connection with 
the SMBMSG$K_ALIGNMENT_PAGES item. 


SMBMSG$V_PAUSE_COMPLETE When specified, the symbiont is to pause 

when it has completed the current request. 

SMBMSG$V_RESTARTING When specified, indicates that this job was 

previously interrupted and requeued, and is 
now restarting. 

SMBMSG$V_TOP_OF_FILE When specified, the symbiont is to rewind 

the input file before it resumes printing. 


SMBMSG$K_REQUEST_RESPONSE 

This code identifies a longword that specifies the type of request for which 
the symbiont is currently signalling completion. The symbiont sends this item 
to the job controller. The following symbols define types of requests that can 
be specified in this item: 


SMBMSG$K_ST ART_STRE AM 
SMBMSG$K_ST ART_T ASK 
SMBMSG$K_RESUME_T ASK 
SMBMSG$K_RESET_STREAM 
SMBMSG$K_T ASK_ST ATUS 


SMBMSG$K_STOP_STREAM 
SMBMSG$K_PAUSE_TASK 
SMBMSG$K_STOP_T ASK 
SMBMSG$K_COMPLETE_T ASK 


SMBMSG$K_RIGHT_MARGIN 

This code identifies a longword that specifies the number of character 
positions to be left empty at the end of each line. The job controller sends 
this item to the symbiont. When the right margin is exceeded, the symbiont 
truncates the line, wraps the line, or continues processing, depending 
on the settings of the WRAP and TRUNCATE bits in the 
SMBMSG$K_PRINT_CONTROL item. 


SMBMSG$K—SEARCH—STRING 

This code identifies a string that contains the value that the user specified in 
the START/QUEUE/SEARCH command. The job controller sends this item 
to the symbiont. This string identifies the page at which to restart the printing 
task current on a paused queue. 

SMBMSG$K_SEPARATION—CONTROL 

This code identifies a longword bit-vector, each bit of which specifies an 
operation that the symbiont is to perform between jobs or between files 
within a job. The job controller sends this item to the symbiont. The 
$SMBDEF macro defines the following symbols for each bit: 
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Symbol 


Description 


SMBMSG$V_FILE _BURST 
SMBMSG$V_FILE_FLAG 
SMBMSG$V_FILE_TRAILER 
SMBMSG$V_FILE_TRAILER_ABORT 

SMBMSG$V_FIRST_FILE_OF_JOB 

SMBMSGSV_IOB—FLAG 

SMBMSG$V_JOB_BURST 

SMBMSG$V_JOB_RESET 

SMBMSG$V_JOB_RESET_ABORT 

SMBMSG$V_JOB_TRAILER 

SMBMSG$V_JOB_TRAILER_ABORT 

SMBMSG$V_LAST_FILE_OF_JOB 


When specified, the symbiont is to 
print a file-burst page. 

When specified, the symbiont is to 
print a file-flag page. 

When specified, the symbiont is to 
print a file-trailer page. 

When specified, the symbiont is to 
print a file-trailer page when a task is 
completed abnormally. 

When specified, the current file is the 
first file of the job. When specified 
with SMBMSG$V_LAST_FILE_OF_JOB, 
the current job contains a single file. 

When specified, the symbiont is to 
print a job-flag page. 

When specified, the symbiont is to 
print a job-burst page. 

When specified, the symbiont is to 
execute a job-reset Sequence when the 
task is completed. 

When specified, the symbiont is to 
execute a job-reset sequence when a 
task is completed abnormally. 

When specified, the symbiont is to 
print a job-trailer page. 

When specified, the symbiont is to 
print a job-trailer page when a task is 
completed abnormally. 

When specified, the current file is the 
last file of the job. When specified with 
SMBMSG$V_FIRST_FILE_OF_JOB, the 
current job contains a single job. 


SMBMSG$K_STOP_CONDITION 

This code identifies a longword that contains a condition that specifies the 
reason the job controller issued a STOP-TASK request. The job controller 
sends this item to the symbiont. 

SMBMSG$K—TIME—QUEUED 

This code identifies a quadword that specifies the time when the file was 
entered into the queue. The time is expressed as 64-bit, absolute time. The 
job controller sends this item to the symbiont. 

SMBMSG$K—TOP—MARGIN 

This code identifies a longword that specifies the number of lines that the 
symbiont is to leave blank at the top of each page. PRTSMB inserts linefeeds 
into the output stream after every formfeed until the margin is cleared. 


SMBMSGSK-UIC 

This code identifies a longword that specifies the User Identification Code 
(UIC) of the user who submitted the job. 
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SMBMSG$K_USER_NAME 

This code identifies a string that specifies the name of the user who submitted 
the job. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine completed successfully 

SMB$_NOMOREITEMS End of item list reached 

Any condition code returned by the Run-Time Library string-handling (STR$) 
routines. 
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SMB$SEND_TO—JOBCTL 



Used by your symbiont to send messages to the job controller. 
Three types of messages can be sent: request-completion 
messages, task-completion messages, and task-status messages. 

FORMAT 

SMB$SEND_TO_JOBCTL stream [,request] 

[,accounting] 

[,checkpoint] 

[, device—status] [, error] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

stream 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Stream number specifying the stream to which the message refers. The 
stream argument is the address of a longword that contains the number of 
the stream to which the message refers. 

request 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Request code identifying the request being completed. The request argument 
is the address of a longword that contains the code that identifies the request 
that has been completed. 

The code usually corresponds to the code that the job controller passed to the 
symbiont by means of a call to SMB$READ_MESSAGE. But the symbiont can 
also initiate task-completion and task-status messages that are not in response 
to a request. (See the Description section.) 
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accounting 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Accounting information about a task. The accounting argument is the address 
of a descriptor that points to the accounting information about a task. Note 
that this structure is passed by descriptor and not by reference. 

See the description of the SMBMSG$K_ACCOUNTING_DATA item for 
more information on this accounting information. 

The following diagram depicts the contents of the 16-byte structure: 


NUMBER OF PAGES PRINTED FOR THE JOB 


READS 


NUMBER OF READS FROM DISK OR TAPE 




WRITES 


NUMBER OF WRITES TO THE PRINTING DEVICE 




UNUSED 
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checkpoint 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Checkpoint data about the currently executing task. The checkpoint 
argument is the address of a descriptor that points to checkpointing 
information that relates to the status of a task. When the symbiont sends 
this information to the job controller, the job controller saves it in the queue's 
data file. When a restart-from-checkpoint request is executed for the queue, 
the job controller retrieves the checkpointing information from the queue's 
data file and sends it to the symbiont in the SMBMSG$K_CHECKPOINT_ 
DATA item that accompanies a SMBMSG$K_START_TASK request. 

Print symbionts can use the checkpointing information to reposition the 
input file to the point corresponding to the page being output when the last 
checkpoint was taken. Other symbionts might use checkpoint information to 
specify restart information for partially completed tasks. 


Note: Because each checkpoint causes information to be written into the 

job controller's queue-data file, taking a checkpoint incurs significant 
overhead. Use caution in regard to the size and frequency of checkpoints. 
When determining how often to checkpoint, weigh processor and file¬ 
system overhead with the convenience of restarting. 
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device—status 


VMS Usage: 
type: 
access: 
mechanism: 


longword_unsigned 
longword (unsigned) 
read only 
by reference 


The status of the device served by the symbiont. The device_status 
argument is the address of a longword passed to the job controller that 
contains the status of the device to which the symbiont is connected. 

This longword contains a longword bitvector, each bit of which specifies 
device-status information. The $SMBDEF macro defines these device-status 
bits. The following describes each bit and its meaning. 


Device Status Bit 

SMBMSG$V_LOWERCASE 

SMBMSG$V_PAUSE_T ASK 

SMBMSG$V_REMOTE 

SMBMSG$V_SERVER 
SMBMSG$V_ST ALLED 
SMBMSG$V_STOP_STREAM 

SMBMSG$V_TERMINAL 
SMBMSG$V_UN AVAILABLE 


Description 

The device to which the symbiont is connected 
supports lowercase characters. 

The symbiont sends this message to inform the 
job controller that the symbiont has paused on 
its own initiative. 

The device is connected to the symbiont by 
means of a modem. 

The symbiont is not connected to a device. 
Symbiont processing is temporarily stalled. 

The symbiont requests that the job controller 
stop the queue. 

The symbiont is connected to a terminal. 

The device to which the symbiont is connected 
is not available. 


error 

VMS Usage: 
type: 
access: 
mechanism: 


vector_longword_unsigned 
longword (unsigned) 
read only 
by reference 


Condition codes returned by the requested task. The error argument is the 
address of a vector of longword condition codes. The first longword contains 
the number of longwords following it. 

If the low bit of the first condition code is clear, the job controller aborts 
further processing of the job. Output of any remaining files, copies of files, or 
copies of the job is canceled. In addition, the job controller saves up to three 
condition values in the queue's data file. The first condition value is included 
in the job-accounting record that is written to the system's accounting file 
(SYSSMANAGER: ACCOUNTNG.DAT). 
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DESCRIPTION 
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The symbiont uses the SMB$SEND_TO_JOBCTL routine to send messages 
to the job controller. 

Most messages the symbiont sends to the job controller are responses to 
requests made by the job controller. These responses inform the job controller 
that the request has been completed, either successfully or with an error. The 
fact that the symbiont sends the message usually indicates that the request 
has been completed. 

In such messages, the request argument corresponds to the function code 
of the request that has been completed. Thus, if the job controller sends a 
request using the SMBMSG$K—START-TASK code, the symbiont responds 
by sending a SMB$SEND_TO_JOBCTL message using SMBMSG$K —START- 
TASK as the request argument. 

The responses to some requests use additional arguments to send more 
information in addition to the request code. The following list shows which 
additional arguments are allowed in response to each different request. 


Request 

Arguments 

SMBMSG$K_ST ART-STREAM 

request 


device_status 


error 

SMBMSG$K_STOP_STREAM 

request 

SMBMSG$K_RESET_STREAM 

request 

SMBMSG$K_ST ART_T ASK 

request 

SMBMSG$K_PAUSE_TASK 

request 

SMBMSG$K_RESUME_TASK 

request 

SMBMSG$K_STOP_TASK 

request 


error * 


*—(This is usually the value specified in the SMBMSG$K_STOP_ 
CONDITION item that was sent by the job controller with the SMBMSG$K— 
STOP-TASK request.) 


In addition to responding to requests from the job controller, the symbiont 
can send other messages to the job controller. If the symbiont sends a 
message that is not a response to a request, it uses either the SMBMSG$K_ 
TASK-COMPLETE or SMBMSG$K_TASK_STATUS codes. The following 
table shows the additional arguments that can be used with the messages 
identified by these codes. 

Code 

Arguments 

SMBMSG$K_TASK_COMPLETE 

request 


accounting 


error 

SMBMSG$K_T ASK_ST ATUS 

request 


checkpoint 


device_status 


The symbiont uses the SMB$K_TASK —STATUS message to update the job 
controller on the status of a task during the processing of that task. The 
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checkpoint information passed to the job controller with this message permits 
the job controller to restart an interrupted task from an appropriate point. 

The device-status information permits the symbiont to report changes in 
device's status (device stalled, for example). 

The symbiont can use the SMB$K—TASK—STATUS message to request that 
the job controller send a stop-stream request. It does this by setting the 
stop-stream bit in the device-status argument. 

The symbiont can also use the SMB$K_TASK—STATUS message to notify 
the job controller that the symbiont has paused in processing a task. It does 
so by setting the pause-task bit in the device-status argument. 

The symbiont uses the SMB$K_TASK—COMPLETE message to signal the 
completion of a task. Note that when the symbiont receives a START—TASK 
request, it responds by sending a SMB$SEND_TO_JOBCTL message with 
SMBSMG$K_START—TASK as the request argument. This response means 
that the symbiont has started the task; it does not mean the task has been 
completed. When the symbiont has completed a task, it sends a 

SMB$SEND_TO—JOBCTL message with SMBSMG$K_TASK—COMPLETE as 
the request argument. 

Optionally, the symbiont can specify accounting information when sending a 
task-completion message. The accounting statistics accumulate to give a total 
for the job when the job is completed. 

Also, if the symbiont is aborting the task because of a symbiont-detected 
error, you can specify up to three condition values in the error argument. 
Aborting a task causes the remainder of the job to be aborted. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine completed successfully 

Any conditions returned by $QIO system service and LIB$GET_VM routine. 
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Introduction To SOR Routines 


The SOR routines allow you to integrate a sort or merge operation into a 
program application. Using these callable routines, you can process some 
records, sort or merge them, and then process them again. 


The following SOR routines are available for use in a sort or merge operation: 


SOR$BEGIN_MERGE 

SOR$BEGIN_SORT 

SOR$END_SORT 

SOR$PASS_FILES 

SORSRELEASE—REC 

SOR$RETURN_REC 

SOR$SORT_MERGE 

SOR$SPEC_FILE 

SORSSTAT 


Sets up key arguments and performs the merge. This is 
the only routine that is unique to MERGE. 

Initializes sort operation by passing key information and 
sort options. This is the only routine that is unique to 
SORT. 

Performs cleanup functions, such as closing files and 
releasing memory. 

Passes names of input and output files to SORT or 
MERGE; must be repeated for each input file. 

Passes one input record to SORT or MERGE; must be 
called once for each record. 

Returns one sorted or merged record to a program; 
must be called once for each record. 

Sorts the records. 

Passes a specification file or specification text. A call 
to this routine must precede all other calls to the SOR 
routines. 

Returns a statistic about the sort or merge operation. 


Note: SOR$DO_MERGE (from VAX/VMS Version 3.0) can still be called as 

the equivalent of SOR$END-SORT; SOR$INIT—MERGE and SOR$INIT_ 
SORT (from VAX/VMS Version 3.0) can still be called as the equivalent 
of SOR$BEGIN_SORT and SOR$BEGIN—MERGE. However, for any new 
programs that you are creating, you are advised to use SOR$END—SORT, 
SOR$BEGIN_SORT, and SOR$BEGIN-MERGE. 

These SOR routines can be called from any language that supports the VAX 
Procedure Calling and Condition Handling Standard. 

After being called, each of these routines performs its function and returns 
control to a program. It also returns a 32-bit condition code value indicating 
success or error that a program can test to determine success or failure 
conditions. 
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11.1.1 Arguments to SOR Routines 

For a sort operation, the arguments to the SOR routines provide SORT with 
file specifications, key information, and instructions about the sorting process. 
For a merge operation, the arguments to the SOR routines provide MERGE 
with the number of input files, input and output file specifications, record 
information, key information, and input routine information. 

There are both mandatory and optional arguments. The mandatory 
arguments appear first in the argument list. You must specify all arguments 
in the order in which they are positioned in the argument list, separating each 
with a comma. Pass a zero by value to specify any optional arguments that 
you are omitting from within the list. You can end the argument list any time 
after specifying all the mandatory and desired optional arguments. 


11.1.2 Interfaces to SOR Routines 

You can submit data to the SOR routines as complete file(s) or as single 
records. When your program submits one or more files to SORT or MERGE, 
which then creates one sorted or merged output file, you are using the 
file interface. When your program submits records one at a time and then 
receives the ordered records one at a time, you are using the record interface. 

You can combine the file interface with the record interface by submitting 
file(s) on input and receiving the ordered records on output, or by releasing 
records on input and writing the ordered records to a file on output. 
Combining the two interfaces provides greater flexibility. If you use the 
record interface on input, you can process the records before they are sorted; 
if you use the record interface on output, you can process the records after 
they are sorted. 

The SOR routines used and the order in which they are called depends on 
the type of interface used in a sorting or merging operation. The following 
sections detail the calling sequence for each of the interfaces. Note, however, 
that if the SOR$STAT routine is used, it must be called before any other SOR 
routine. 


11.1.2.1 Sort Operation Using File Interface 

For a sort operation using the file interface, pass the input and output 
file specifications to SORT by calling SOR$PASS_FILES. You must call 
SOR$PASS_FILES for each input file specification. Pass the output file 
specification in the first call. If no input files are specified before the call to 
SOR$BEGIN_SORT, the record interface is used for input; if no output file is 
specified, the record interface is used for output. 

Next, call SOR$BEGIN_SORT, to pass instructions about keys and sort 
options. At this point, you must indicate if you want to use your own key 
comparison routine. SORT automatically generates a key comparison routine 
that is efficient for key data type(s); however, you may want to provide your 
own comparison routine to handle special sorting requirements. (For example, 
you may want names beginning with "Me" and "Mac" to be placed together.) 
If you use your own key comparison routine, you must pass its address with 
the user_compare argument. 

Call SOR$SORT_MERGE to execute the sort and direct the sorted records 
to the output file. Finally, call SOR$END_SORT to end the sort and release 
resources. The SOR$END_SORT routine may be called at any time to abort a 
sort, or merge and release all resources allocated to the sort or merge process. 
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11.1.2.2 Sort Operation Using Record Interface 

For a sort operation using the record interface, first call SOR$BEGIN_SORT. 
As in the file interface, this routine sets up work areas and passes arguments 
that define keys and sort options. Note that, if you use the record interface, 
you must use a record sorting process (not a tag, address or index process). 

Next, call SOR$RELEASE_REC to release a record to SORT. Call 
SOR$RELEASE_REC once for each record to be released. After all records 
have been passed to SORT, call SOR$SORT_MERGE to perform the sorting. 

After the sort has been performed, call SOR$RETURN_REC to return a 
record from the sort operation. Call this routine once for each record to be 
returned. Finally, call the last routine, SOR$END_SORT, to complete the sort 
operation and release resources. 


11.1.2.3 Merge Operation Using File Interface 

For a merge operation using the file interface, pass the input and output 
file specifications to MERGE by calling SOR$PASS_FILES. You can merge 
up to 10 input files; call SOR$PASS_FILES once for each file. Pass the file 
specification for the merged output file in the first call. If no input files are 
specified before the call to SOR$BEGIN—MERGE, the record interface is used 
for input; if no output file is specified, the record interface is used for output. 

Next, call SOR$BEGIN —MERGE to pass key information and merge options, 
to execute the merge. At this point, you must indicate if you want to use your 
own key comparison routine tailored to your data. Finally, call 
SOR$END_SORT to release resources. 


11.1.2.4 Merge Operation Using Record Interface 

For a merge operation using the record interface, first call 
SOR$BEGIN_MERGE. As in the file interface, this routine passes arguments 
that define keys and merge options. It also issues the first call to the input 
routine, which you must create, to begin releasing records to the merge. 

Next, call SOR$RETURN_REC to return the merged records to your 
program. You must call this routine once for each record to be returned. 
SOR$RETURN_REC continues to call the input routine. MERGE, unlike 
SORT, does not need to hold all the records before it can begin returning 
them in the desired order. The releasing, merging, and returning of records 
all take place in this phase of the merge. 

Finally after all the records have been returned, call the last routine, 
SOR$END_SORT to clean up and release resources. 


11.1.3 Reentrancy 

The SOR routines are reentrant, that is, a number of sort or merge operations 
can be active at the same time. Thus, a program does not need to finish one 
sort or merge operation before beginning another. For example, reentrancy 
allows you to perform multiple sorts on a file such as a mailing list and to 
create several output files, one with the records sorted by name, another 
sorted by state, another sorted by zip code, and so on. 

The context argument, which may optionally be passed with any of the SOR 
routines, distinguishes among multiple sort or merge operations. When using 
multiple sort or merge operations, the context argument is required. On the 
first call, the context longword must be zero. It is then set (by SORT/MERGE) 
to a value that identifies the sort or merge operation. Additional calls to the 
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same sort or merge operation must pass the same context longword. The 
SOR$END_SORT routine clears the context longword. 


11.2 Examples Of Using SOR Routines 

The following example is a FORTRAN program demonstrating a merge 
operation using a record interface. 
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Example SOR-1 


Using SOR Routines to Perform a Merge Using 
Record Interface in a FORTRAN Program 


FORTRAN Program 


C. . . 

C... This program demonstrates the FORTRAN calling sequences 
C... for the merge record interface. 

C. . . 

C 

C THE INPUT FILES ARE LISTED BELOW. 


C 

C INFILE1.DAT 

C 

C 1 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 2 UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 

C 

C INFILE2.DAT 

C 

C 1 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 2 TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C 

C INFILE3.DAT 

C 

C 1 ttttttTTTT REST OF DATA IN RECORD.END OF RECORD 

C 2 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 

C FOROUT.DAT 

C 

C 1 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 1 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 1 TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C 2 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 2 TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C 2 UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 

C 

C 

C. 

C 

C 



IMPLICIT INTEGER (A-Z) 
CHARACTER * 80 REC 

EXTERNAL READ.REC 
EXTERNAL KOMPAR 
EXTERNAL SS$_ENDOFFILE 


INTEGERS SOR$BEGIN_MERGE 
INTEGER*4 SOR$RETURN_REC 
INTEGERS SOR$END_SORT 
INTEGER*4 ISTAT 
INTEGER*4 LENGTH 
INTEGER*2 LRL 


LOGICAL*! ORDER 


DATA ORDER,LRL/3,80/ 


! A record. 

! Routine to read a record. 

! Routine to compare records. 

! System end-of-file value 

! SORT/MERGE function names 

! storage for SORT/MERGE function value 
! length of the returned record 
! Longest Record Length (LRL) 

! #files to merge (merge order) 

! Order of the merge=3,LRL=80 


(Continued on next page) 
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Example SOR-1 (Cont.) Using SOR Routines to Perform a 

Merge Using Record Interface in a 
FORTRAN Program 


c... 

C... First open all the input files. 

C. . . 

OPEN (UNIT=10, FILE='INFILE1.DAT'.TYPE*'OLD'.READONLY, 

* F0RM='FORMATTED') 

OPEN (UNIT=11, FILE*•INFILE2.DAT',TYPE='OLD',READONLY, 

* FORM-'FORMATTED') 

OPEN (UNIT*12. FILE*'INFILE3.DAT•,TYPE*'OLD',READONLY, 

* FORM*'FORMATTED') 

C 

C... Open the output file. 

C 

OPEN (UNIT=8, FILE*'TEMP.TMP', TYPE*'NEW') 

C. . . 

C... Initialize the merge. Pass the merge order, the largest 
C... record length, the compare routine address, and the 
C... input routine address. 

C. . . 

ISTAT = SOR$BEGIN_MERGE (.LRL,,ORDER, 

* KOMPAR,,READ_REC) 

IF (.NOT. ISTAT) GOTO 10 ! Check for error. 

C. . . 

C... Now loop getting merged records. SOR$RETURN_REC will 
C... call READ_REC when it needs input. 

C. . . 

5 ISTAT = SOR$RETURN_REC (REC, LENGTH) 

IF (ISTAT .EQ. */.LOC(SS$_ENDOFFILE)) GO TO 30 ! Check for end of file. 

IF (.NOT. ISTAT) GO TO 10 ! Check for error. 

WRITE(8.200) REC ! Output the record. 

200 FORMAT(' '.A) 

GOTO 5 ! And loop back. 

C. . . 

C... Now tell SORT that we are all done. 

C. . . 

30 ISTAT = S0R$END_S0RT() 

IF (.NOT. ISTAT) GOTO 10 ! Check for error. 

CALL EXIT 

C. . . 

C. .. Here if an error occurred. Write out the error status 
C... and exit. 

C. . . 

10 WRITE(8.201)ISTAT 

201 FORMAT(' TERROR CODE', 120) 

CALL EXIT 

END 


(Continued on next page) 
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Example SOR-1 (Cont.) Using SOR Routines to Perform a 

Merge Using Record Interface in a 
FORTRAN Program 


FUNCTION READ.REC (RECX, FILE, SIZE) 

C. . . 

C... This routine reads a record from one of the input files 
C... for merging. It will be called by SOR$BEGIN.MERGE and by 
C... SOR$RETURN_REC. 

C... Parameters: 

C. . . 

C... RECX.wcp.ds 

C. . . 

C. . . 

C... FILE.rl.r 

C. . . 

C. . . 

C. . . 

C. . . 

C... LENGTH.wl.r 

C. . . 

C. . . 

IMPLICIT INTEGER (A-Z) 

PARAMETER MAXFIL=10 

EXTERNAL SS$_ENDOFFILE 
EXTERNAL SS$_NORMAL 

LOGICAL+1 FILTAB(MAXFIL) 

CHARACTER*(80) RECX ! MAX LRL =80 

DATA FILTAB/10,11,12,13,14,15,16,17,18,19/ ! Table of I/O unit numbers. 

READ.REC = */.L0C(SS$_END0FFILE) ! Give end of file return 

IF (FILE .LT. 1 .OR. FILE .GT. MAXFIL) RETURN ! if illegal call. 

READ (FILTAB(FILE). 100, ERR=75, END=50) RECX ! Read the record. 

100 FORMAT(A) 



READ.REC = 

*/,L0C (SS$_N0RMAL) 

! Return 

success 

code. 


SIZE = LEN 

RETURN 

(RECX) 

! Return 

size 

of 

record. 

c.. . 

Here if end of file. 





50 

READ.REC = 

7.L0C (SS$_ENDOFFILE) 

! Return 

"end 

of 

file” code 


RETURN 


C... Here if error while reading 
75 READ.REC = 0 

SIZE = 0 
RETURN 
END 


character buffer to hold the record after 
it is read in. 

indicates which file the record is 
to be read from. 1 specifies the 
first file, 2 specifies the second 
etc. 

is the actual number of bytes in 
the record. This is set by READ.REC. 

! Max number of files. 

! End of file status code. 
! Success status code. 


(Continued on next page) 


SOR—7 






Sort/Merge (SOR) Routines 

Examples Of Using SOR Routines 


Example SOR-1 (Cont.) Using SOR Routines to Perform a 

Merge Using Record Interface in a 
FORTRAN Program 


FUNCTION KOMPAR (REC1.REC2) 

C. . . 

C... This routine compares two records. It returns -1 

C... if the first record is smaller than the second, 

C... 0 if the records are equal, and 1 if the first record 

C... is larger than the second. 

C. . . 

PARAMETER KEYSIZ=10 
IMPLICIT INTEGER (A-Z) 

LOGICAL*1 REC1(KEYSIZ),REC2(KEYSIZ) 

DO 20 1=1,KEYSIZ 

KOMPAR = RECl(I) - REC2(I) 

IF (KOMPAR .NE. 0) GOTO 50 

20 CONTINUE 

RETURN 

50 KOMPAR = ISIGN (1, KOMPAR) 

RETURN 

END 


The following example is a FORTRAN program demonstrating a sort 
operation using a file interface on input and a record interface on output. 
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Example SOR-2 Using SOR Routines to Sort Using Mixed 

Interface in a VAX FORTRAN Program 


Program 


PROGRAM CALLSORT 


C 

C 

C This is a sample FORTRAN program that calls the SOR 

C routines using the file interface for input and the 

C record interface for output. This program requests 

C a record sort of the file 'R010SQ.DAT' and writes 

C the records to SYS$OUTPUT. The key is an 80-byte 

C character ascending key starting in position 1 of 

C each record. 

C 

C A short version of the input and output files follows: 


C 

C Input file R010SQ.DAT 

C 1 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 2 UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 

C 1 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 2 TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C i TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C 2 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 1 QQQQQQQQQQ REST OF DATA IN RECORD.END OF RECORD 

C 2 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 1 UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 

C 2 QQQQQQQQQQ REST OF DATA IN RECORD.END OF RECORD 

C 

C Output file SYSSOUTPUT 

C 

C 1 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 1 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 1 QQQQQQQQQQ REST OF DATA IN RECORD.END OF RECORD 

C 1 TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C i UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 

C 2 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 2 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 2 QQQQQQQQQQ REST OF DATA IN RECORD.END OF RECORD 

C 2 TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C 2 UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 

C 

C...-.. 

C 

C Define external functions and data. 

C 


CHARACTER*80 RECBUF 
CHARACTER*10 INPUTNAME 
INTEGER*2 KEYBUF(5) 
INTEGER*4 SOR$PASS_FILES 
INTEGER*4 SOR$BEGIN_SORT 
INTEGER*4 SOR$SORT_MERGE 
INTEGER*4 SOR$RETURN_REC 
INTEGER*4 SOR$END_SORT 
INTEGER*4 ISTATUS 
EXTERNAL SS$_ENDOFFILE 
EXTERNAL DSC$K_DTYPE_T 
EXTERNAL SOR$GK_RECORD 
INTEGER*4 SRTTYPE 


!Input file name 
!Key definition buffer 
ISORT function names 


!Storage for SORT function value 


(Continued on next page) 
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Example SOR-2 (Cont.) Using SOR Routines to Sort Using 

Mixed Interface in a VAX FORTRAN 
Program 


c 

C Initialize data — first the file names, then the key buffer for 

C one 80-byte character key starting in position 1, 3 work files, 

C and a record sort process. 

C 

DATA INPUTNAME/'R010SQ.DAT'/ 

KEYBUF(1) = 1 

KEYBUF(2) = */,L0C (DSC$K_DTYPE_T) 

KEYBUF(3) = 0 
KEYBUF(4) = 0 
KEYBUF(5) = 80 

SRTTYPE = '/,L0C (S0R$GK_REC0RD) 

C 

C Call the SORT -- each call is a function. 

C 

C 

C Pass SORT the file names. 

C 

ISTATUS = SOR$PASS_FILES(INPUTNAME) 

IF (.NOT. ISTATUS) GOTO 10 
C 

C Initialize the work areas and keys. 

C 

ISTATUS = S0R$BEGIN_S0RT (KEYBUF,,,,,, SRTTYPE,‘/.REF (3)) 

IF (.NOT. ISTATUS) GOTO 10 
C 

C Sort the records. 

C 

ISTATUS = S0R$S0RT_MERGE( ) 

IF (.NOT. ISTATUS) GOTO 10 
C 

C Now retrieve the individual records and display them. 

C 

5 ISTATUS = SOR$RETURN_REC(RECBUF) 

IF (.NOT. ISTATUS) GOTO 6 
ISTATUS = LIB$PUT_OUTPUT(RECBUF) 

GOTO 5 

6 IF (ISTATUS .EQ. 7.L0C(SS$_END0FFILE)) GOTO 7 
GOTO 10 

C 

C Clean up the work areas and files. 

C 

7 ISTATUS = S0R$END_S0RT() 

IF (.NOT. ISTATUS) GOTO 10 
STOP 'SORT SUCCESSFUL' 

10 STOP 'SORT UNSUCCESSFUL' 

END 


The following example is a Pascal program demonstrating a merge operation 
using a file interface. 
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Example SOR-3 Using SOR Routines to Merge Three Input 
Files in a VAX PASCAL Program 


Program 

(* This program merges three input files, (IN_FILE.DAT, 

IN_FILE2.DAT IN_FILE3.DAT), and creates one merged output file. *) 

program mergerecs( output, in.filel, in_file2, in_file3, out.file ); 

CONST 

SS$_NORMAL = i; 

SS$_ENDOFFILE * 7.X870; 

SOR$GK_RECORD = 1; 

SOR$M_STABLE = 1; 

SOR$M_SEQ_CHECK = 4; 

SOR$M_SIGNAL = 8; 

DSC$K_DTYPE_T = 14; 

TYPE 

$UBYTE = [BYTE] 0..255; 

$UW0RD = [WORD] 0..65535; 

const 

num_of_keys = 1; 
merge.order = 3; 
lrl = 131; 

ascending = 0; 
descending = 1; 

type 

key_bufferJblock= 
packed record 
key_type: 
key_order: 
key_offset: 
key.length: 
end; 

key_buffer_type= 

packed record 
key.count: 
blocks: 
end; 

record_buffer = 

record_buffer_descr = 
packed record 
length: $uword; 
dummy: $uword; 

addr: ~record_buffer; 

end; 


$uword; 
$uword; 
$uword; 
$uword; 


$uword; 

packed array[1..num_of_keys] of key.buffer_block; 
packed array[1..lrl] of char; 


(Continued on next page) 
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Example SOR-3 (Cont.) Using SOR Routines to Merge Three 

Input Files in a VAX PASCAL Program 


in.filel, 
in_file2, 
in_file3, 
out_file: 
key_buffer: 
rec.buffer: 
rec_length: 
status: 
i: 


text; 

key_buffer_type; 
record.buffer; 
$uword; 
integer; 
integer; 


function sor$begin_merge( 

var buffer: key.buffer.type; 

lrl: $uword; 

mrg_opti on s: integer; 

merge_order: $ubyte; 

%immed cmp.rtn: integer := 0; 

%immed eql.rtn: integer := 0; 

Rimmed [unbound] function 
read_record( 

var rec: record_buffer.descr; 

var filenumber: integer; 

var recordsize: $uword): integer 
): integer; extern; 

function sor$return_rec( 

'/.stdescr rec: record.buffer; 

var rec.size: $uword 

): integer; extern; 

function sor$end_sort: integer; extern; 

procedure sys$exit( dimmed status : integer ); extern; 

function read_record( 

var rec: record_buffer.descr; 

var filenumber: integer; 
var recordsize: $uword 
): integer; 

procedure readone( var filename: text ); 

begin 

recordsize :■ 0; 

if eof(filename) 

then 

read_record := ss$_endoffile 

else 

begin 

while not eoln(filename) and (recordsize < rec.length) do 
begin 

recordsize := recordsize + 1; 

read(filename,rec.addr~[recordsize]); 

end; 

readln(filename); 

end; 

end; 


(Continued on next page) 
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Example SOR-3 (Cont.) Using SOR Routines to Merge Three 

Input Files in a VAX PASCAL Program 


begin 

read.record := ss$_normal; 
case filenumber of 

1: readone(in_filel); 

2: readone(in_file2); 

3: readone(in_file3); 
otherwise 

read.record :* ss$_endoffile; 

end; 

end; 

procedure initfiles; 
begin 

open( in_filel, 'infilel.dat', old ); 

open( in_file2, 'infile2.dat', old ); 

open( in_file3, 'infile3.dat', old ); 

open( out_file, 'temp.tmp' ); 

reset( in.filel ); 

reset( in_file2 ); 

reset( in_file3 ); 

rewrite( out.file ); 

end; 

procedure error( status : integer ); 
begin 

writeln( 'merge unsuccessful. status^Xx', status:8 hex ); 

sys$exit(status); 

end; 

begin 

with key.buffer do 
begin 

key_count := 1; 
with blocks[1] do 
begin 

key.type := dsc$k_dtype_t; 
key.order : = ascending; 
key_offset := 0; 
key.length := 5; 
end; 

end; 

initfiles; 

status :* sor$begin_merge( key_buffer, lrl, 

8or$m_seq_check + sor$m_signal, 
merge_order, 0, 0, read_record ); 


(Continued on next page) 
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Example SOR-3 (Cont.) Using SOR Routines to Merge Three 

Input Files in a VAX PASCAL Program 


repeat 

begin 

rec_length := 0; 

status := sor$return_rec( rec_buffer, rec_length ); 

if odd(status) 

then 

begin 

for i := 1 to rec.length do write(out_file, rec.buffer[i]); 

writeln(out_file); 

end; 

end 

until not odd(status); 

if status <> ss$_endoffile then error(status); 

status := sor$end_sort; 

if not odd(status) then error(status); 

writeln( 'merge successful.' ); 
end. 


The following example is a Pascal program demonstrating a sort operation 
using a record interface. 
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Example SOR-4 Using SOR Routines to Sort Records from Two 
Input Files in a VAX PASCAL Program 


PASCAL Program 

PROGRAM FILETORECORDSORT (OUTPUT,SORTOUT); 

(* This program calls SOR routines to read and sort records from 

two input files, (PASINPUT1.DAT and PASINPUT2.DAT) and to return 
sorted records to this program to be written to the output file, 

(TEMP.TMP). *) 

(* Declarations for external status codes, and data structures, such as 

the types $UBYTE (an unsigned byte) and $UW0RD (an unsigned word). *) 

CONST 

SSS.NORMAL = 1; 

SSS.ENDOFFILE * %X870; 

SOR$GK_RECORD = 1; 

SOR$M_STABLE = 1; 

SOR$M_SEQ_CHECK = 4; 

SOR$M_SIGNAL = 8; 

DSC$K_DTYPE_T = 14; 

TYPE 

$UBYTE = [BYTE] 0..255; 

$UW0RD = [WORD] 0..65535; 

CONST 

Numberofkeys = 1 ; 

LRL = 131 ; 

(* Key orders *) 

Ascending = 0 ; 

Descending = 1 ; 

TYPE 

Keybufferblock= packed record 

Keytype : $UW0RD ; 

Keyorder : $UW0RD ; 

Keyoffset : $UW0RD ; 

Keylength : $UW0RD 
end ; 

(* The keybuffer. Note that the field buffer is a one-component array in 
this program. This type definition would allow a multikeyed sort. *) 

Keybuffer= packed record 

Numkeys : $UW0RD ; 

Blocks : packed array[1..Numberofkeys] OF Keybufferblock 
end ; 


(* Number of keys for this sort *) 

(* Longest Record Length for output records *) 


(Continued on next page) 
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Examples Of Using SOR Routines 


Example SOR-4 (Cont.) Using SOR Routines to Sort Records 

from Two Input Files in a VAX 
PASCAL Program 


(* The record buffer. This buffer will be used to hold the returned 
records from SORT. *) 

Recordbuffer * packed array[1..LRL] of char ; 

(« Name type for input and output files. A necessary fudge for %stdescr 
mechanism. *) 

nametype= packed array[1..13] of char ; 


VAR 

Sortout : text ; 

Buffer : Keybuffer ; 
Sortoptions : integer ; 
Sorttype : $UBYTE ; 
Numworkfiles : $UBYTE ; 
Status : integer ; 

Rec : Recordbuffer ; 
Recordlength : $UWORD ; 
Inputname: nametype ; 

i : integer ; 


(* the output file *) 

(* the actual keybuffer *) 

(* flag for sorting options *) 

(* sorting process *) 

(* number of work files *) 

(* function return status code *) 
(* a record buffer *) 

(* the returned record length *) 
(* input file name *) 

(* loop control variable *) 


(* function and procedure declarations *) 

(* Declarations of SORT functions *) 

(* Note that the following SORT routine declarations 

do not use all of the possible routine parameters. *) 

(* The parameters used MUST have all preceding parameters specified, 
however. *) 

FUNCTION SOR$PASS_FILES 

(%STDESCR Inname : nametype ) 

: INTEGER ; EXTERN ; 

FUNCTION SOR$BEGIN_SORT( 

VAR Buffer : Keybuffer ; 

Lrlen : $UWORD ; 

VAR Sortoptions : INTEGER ; 

RIMMED Filesize : INTEGER ; 

•/.IMMED Usercompare : INTEGER ; 

DIMMED Userequal : INTEGER ; 

VAR Sorttype : lUBYTE ; 

VAR Numworkfiles : $UBYTE ) 

: INTEGER ; EXTERN ; 


(Continued on next page) 
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Examples Of Using SOR Routines 


Example SOR-4 (Cont.) Using SOR Routines to Sort Records 

from Two Input Files in a VAX 
PASCAL Program 


FUNCTION SOR$SORT_MERGE 
: INTEGER ; EXTERN ; 

FUNCTION SOR$RETURN_REC( 

'/.STDESCR Rec : Recordbuffer ; 

VAR Recordsize : $UW0RD ) 

: INTEGER ; EXTERN ; 

FUNCTION SOR$END_SORT 
: INTEGER ; EXTERN ; 

(* End of the SORT function declarations *) 

(* The CHECKSTATUS routine checks the return status for errors. *) 

(* If there is an error, write an error message and exit via sys$exit *) 
PROCEDURE CHECKSTATUS( var status : integer ) ; 

procedure sys$exit( status : integer ) ; extern ; 

begin (* begin checkstatus *) 

if odd(status) then 
begin 

writeln( ' SORT unsuccessful. Error status = status:8 hex ) ; 
SYS$EXIT( status ) ; 
end ; 

end ; (* end checkstatus *) 

(* end function and routine declarations *) 

BEGIN (* begin the main routine *) 

(* Initialize data for one 8-byte character key, starting at record 
offset 0, 3 work files, and the record sorting process *) 

Inputname := 'PASINPUT1.DAT' ; 

WITH Buffer DO 
BEGIN 

Numkeys := 1; 

WITH Blocks[1] DO 
BEGIN 

Keytype := DSC$K_DTYPE_T ; (* Use VMS descriptor data types to 

define SORT data types. *) 

Keyorder := Ascending ; 

Keyoffset := 0 ; 

Keylength := 8 ; 

END; 

END; 


(Continued on next page) 
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Sort/Merge (SOR) Routines 

Examples Of Using SOR Routines 


Example SOR-4 (Cont.) Using SOR Routines to Sort Records 

from Two Input Files in a VAX 
PASCAL Program 


Sorttype := S0R$GK_REC0RD ; 
Sortoptions := SOR$M_STABLE ; 
Numworkfiles 3 ; 


(* Use the global SORT constant to 
define the sort process. *) 

(* Use the global SORT constant to 

define the stable sort option. *) 


(* call the sort routines as a series of functions *) 

(* pass the first filename to SORT *) 

Status : = SOR$PASS_FILES( Inputname ) ; 

(* Check status for error. *) 

CHECKSTATUSC Status ) ; 

(* pass the second filename to SORT *) 

Inputname :» 'PASINPUT2.DAT' ; 

Status := SOR$PASS_FILES( Inputname ) ; 

(* Check status for error. *) 

CHECKSTATUSC Status ) ; 

(* initialize work areas and keys *) 

Status S0R$BEGIN_S0RT( Buffer, 0, Sortoptions, 0, 0, 0, 

Sorttype, Numworkfiles ) ; 

C* Check status for error. *) 

CHECKSTATUSC Status ) ; 

C* sort the records *) 

Status := S0R$S0RT_MERGE ; 


C* Check status for error. *) 

CHECKSTATUSC Status ) ; 

C* Ready output file for writting returned records from SORT. *) 

OPENC S0RT0UT, 'TEMP.TMP' ) ; 

REWRITEC S0RT0UT ) ; 

C* Now get the sorted records from SORT. *) 

Recordlength := 0 ; 

REPEAT 

Status := S0R$RETURN_RECC Rec, Recordlength ) ; 
if oddC Status ) 

then C* if successful, write record to output file. *) 

begin 

for i := 1 to Recordlength do 

write C sortout, Rec[i] ) ; C* write each character *) 
writeln C sortout) ; C* end output line *) 

end; 

UNTIL not oddC Status ) ; 


(Continued on next page) 
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Sort/Merge (SOR) Routines 

Examples Of Using SOR Routines 


Example SOR-4 (Cont.) Using SOR Routines to Sort Records 

from Two Input Files in a VAX 
PASCAL Program 


(* If there was just no more data to be returned (eof) continue, otherwise 
exit with an error. *) 
if Status <> SS$_ENDOFFILE then 
CHECKSTATUS( Status ) ; 

(* The sort has been successful to this point. *) 

(* Close the output file *) 

CLOSE( sortout ) ; 

(* clean up work areas and files *) 

Status := S0R$END_S0RT ; 

(* Check status for error. *) 

CHECKSTATUSC Status ); 

WRITELN ('SORT SUCCESSFUL') ; 

END. 


11.3 SOR Routines 


The following pages describe the individual SOR routines in routine template 
format. 
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SOR$BEGIN_MERGE 


SOR$BEGIN_MERGE—Initialize a Merge 

Operation 



Initializes the merge operation by opening the input and output files 
and by providing the number of input files, the key specifications, 
and the merge options. 

FORMAT 

SOR$BEGIN_MERGE [key-buffer][,lrl] 

[, options] [, merge—order] 

[, user—compare] 

[, user—equal] [, user—input] 

[, context] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

key—buffer 

VMS Usage: vector_word_unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Array of words describing the key(s) on which you plan to merge. The 
key_buffer argument is the address of an array containing the key 
descrip tion(s). 

The first word of this array contains the number of keys described (up to 
255). Following the first word, each key is described (in order of priority) 
in blocks of four words. The four words specify the key's data type, order, 
offset, and length, respectively. 

The first word of the block specifies the key's data type. The following data 
types are accepted: 

DSC$K_DTYPE_Z Unspecified (uninfluenced by collating sequence) 

DSC$K_DTYPE_B Byte integer (signed) 

DSC$K_DTYPE_BU Byte (unsigned) 

DSC$K_DTYPE_W Word integer (signed) 

DSC$K_DTYPE_WU Word (unsigned) 

DSC$K_DTYPE_L Longword integer (signed) 
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SOR$BEGIIM—MERGE 


DSC$K_DTYPE_LU 

DSC$K_DTYPE_Q 

DSC$K _DTYPE _QU 

DSC$K_DTYPE_0 

DSC$K_DTYPE_OU 

DSC$K_DTYPE_F 

DSC$K_DTYPE_D 

DSC$K_DTYPE_G 

DSC$K_DTYPE_H 

DSC$K_DTYPE_T 

DSC$K_DTYPE_NU 

DSC$K_DTYPE_NL 

DSC$K_DTYPE_NLO 

DSC$K_DTYPE_NR 

DSC$K_DTYPE_NRO 

DSC$K_DTYPE_NZ 

DSC$K_DTYPE_P 


Longword (unsigned) 

Quadword integer (signed) 

Quadword (unsigned) 

Octaword integer (signed) 

Octaword (unsigned) 

Single-precision floating 
Double-precision floating 
G-format floating 
H-format floating 

Text (may be influenced by collating sequence) 
Numeric string, unsigned 
Numeric string, left separate sign 
Numeric string, left overpunched sign 
Numeric string, right separate sign 
Numeric string, right overpunched sign 
Numeric string, zoned sign 
Packed decimal string 


The VAX Procedure Calling and Condition Handling Standard, documented 
in Section 2 in the Introduction to VAX/VMS System Routines , describes each 
of these data types. 

The second word of the block specifies the key order, 0 for ascending order, 1 
for descending order. The third word of the block specifies the relative offset 
of the key in the record. (Note that the first byte in the record is at position 
0.) The fourth word of the block specifies the key length in bytes (in digits 
for packed decimal—DSC$K_DTYPE_P). 

If you do not specify the key buffer argument, you must pass either a key 
comparison routine or use a specification file to define the key. 


Irl 


VMS Usage: 
type: 
access: 
mechanism: 


word—unsigned 
word (unsigned) 
read only 
by reference 


Length of the longest record that will be released for merging. The lrl 
argument is the address of a word containing the length. This argument is 
not required if the input file is on a disk. It is required when you use the 
record interface. For VFC records, this length must include the length of the 
fixed-length portion of the record. 


options 

VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Flags that identify merge options. The options argument is the address of a 
longword bit mask whose settings determine the merge options selected. The 
bit mask values available are as follows: 
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SOR$BEGI INI—MERGE 


Flag 

Description 

SORSM-STABLE 

Keeps records with equal keys in the same order in 
which they appeared on input. 

SOR$M_EBCDIC 

Orders ASCII character keys according to EBCDIC 
collating sequence. No translation takes place. 

SORSM-MULTI 

Orders character keys according to the multinational 
collating sequence, which collates the international 
character set. 

SOR$M_NOSIGNAL 

Returns a status code instead of signalling errors. (This 
is the default behavior.) 

SOR$M_NODUPS 

Omits records with duplicate keys. You cannot use this 
option if you specify your own equal-key routine. 

SOR$M_SEQ_CHECK 

Requests an "out of order" error return if an input file 
is not already in sequence. By default, this check is 
not done. You must request sequence checking if you 
specify an equal-key routine. 


All other bits in the longword are reserved and must be zero. 


merge—order 


VMS Usage: 
type: 
access: 
mechanism: 


byte_unsigned 
byte (unsigned) 
read only 
by reference 


Number of input streams to be merged. The merge—order argument is the 
address of a byte containing the number of files (1-10) to be merged. This 
argument is required when you use the record interface on input. 


user—compare 

VMS Usage: procedure 
type: procedure entry mask 

access: function call 

mechanism: by reference 


Routine that compares records to determine their merge order. The 
user—compare argument is the address of the entry mask for this user-written 
routine. This argument is required if you do not specify the key—buffer 
argument, or if you define key information in a specification file. 

MERGE calls the comparison routine with five reference arguments—ADRS1, 
ADRS2, LENG1, LENG2, CNTX—the addresses of the two records to be 
compared, the lengths of these two records, and the context longword. 

The comparison routine must return a 32-bit integer value: 

• -1 if the first record collates before the second 

• 0 if the records collate as equal 

• 1 if the first record collates after the second 
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SOR$BEGIN_MERGE 


user—equal 


VMS Usage: 
type: 
access: 
mechanism: 


procedure 

procedure entry mask 
function call 
by reference 


Routine that resolves the merge order when records have duplicate keys. 

The user—equal argument is the address of the entry mask for this user- 
written routine. Do not use this argument if you specify SOR$M—STABLE or 
SOR$M—NODUPS in the options argument. 

MERGE calls the duplicate key routine with five reference arguments— 
ADRS1, ADRS2, LENG1, LENG2, CNTX—the addresses of the two records 
that compare equally, the lengths of the two records that compare equally, 
and the context longword. 

The routine must return a 32-bit condition code: 


Code 

SOR$_DELETE1 

SOR$_DELETE2 

SOR$_DELBOTH 

SS$_NORMAL 


Description 

Delete the first record from the merge 
Delete the second record from the merge 
Delete both records from the merge 
Keep both records in the merge 


Any other failure value causes the error to be signaled or returned. Any other 
success value causes an undefined result. 


user—input 


VMS Usage: 
type: 
access: 
mechanism: 


procedure 

procedure entry mask 
function call 
by reference 


Routine that releases records to the merge operation. The user_input 
argument is the address of the entry mask for this user-written routine. 
SOR$BEGIN-MERGE and SOR$RETURN_REC call this routine until all 
records have been passed. 

This input routine must read (or construct) a record, place it in a record buffer, 
store its length in an output argument, and then return control to MERGE. 

The input routine must accept the following four arguments: 

• A descriptor of the buffer where the routine must place the record 

• A longword, passed by reference, containing the stream number from 
which to input a record (the first file is 1, the second 2, and so on) 

• A word, passed by reference, where the routine must return the actual 
length of the record 

• The context longword, passed by reference 


The input routine must also return a status value. 

• SS$_NORMAL or any other success status causes the merge operation to 
continue 

• SS$_ENDOFFILE indicates that no more records are in the file. The 
contents of the buffer are ignored. 
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• Any other error status terminates the merge operation and passes 
the status value back to the caller of SOR$BEGIN—MERGE or 
SOR$RETURN_REC. 


context 


VMS Usage: 
type: 
access: 
mechanism: 


context 

longword (unsigned) 

modify 

by reference 


Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for 
the same operation, you must pass the context value that was supplied by 
SORT/MERGE. 


DESCRIPTION The SOR$BEGIN_MERGE routine initializes the merge process by passing 

arguments that provide the number of input streams, the key specifications, 
and any merge options. 

You must define the key by passing either the key buffer address argument 
or your own comparison routine address. (You can also define the key in a 
specification file and call the SOR$SPEC_FILE routine.) 

The SOR$BEGIN_MERGE routine initializes the merge process in the file, 
record, and mixed interfaces. For record interface on input, you must also 
pass the merge order, the input routine address, and the longest record 
length. For files not on disk, you must pass the longest record length. 

Some of the following values are used with different severities depending 
on whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 


CONDITION SSS—NORMAL 

VALUES SOR$_BADDTYPE 

R ETU R NED sor$_b adlenoff 

SOR$_BADLOGIC 

SOR$_BADOCCURS 

SOR$_BADOVRLAY 

SOR$_BADPROTCL 

SOR$_BAD_KEY 

SOR$_BAD_LRL 

SOR$_BAD_MERGE 

SOR$_BAD_ORDER 

SOR$_BAD_SRL 

SOR$_BAD_TYPE 


Success. 

Invalid or unsupported CDD datatype. 

Length and offset must be multiples of 8 bits. 
Internal logic error detected. 

Invalid OCCURS clause. 

Invalid overlay structure. 

Node is an invalid CDD object. 

Invalid key specification. 

Record length n greater than specified longest 
record length. 

Number of work files must be between 0 and 10. 
Merge input is out of order. 

Record length n is too short to contain keys. 
Invalid sort process specified. 
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SOR$_CDDERROR 
SOR$_CLOSEIN 
SOR$_CLOSEOUT 
SORS—COL _CH AR 
SOR$_COL _CMPLX 
SOR$_COL _PAD 
SOR$_COL —THREE 
SOR$_ENDDIAGS 
SOR$_ILLBASE 
SOR$_ILLLITERL 
SOR$_ILLSCALE 
SOR$_INCDIGITS 

SORS—INCNOD AT A 

SOR$_INCNOKEY 

SOR$_IND_OVR 

SOR$_KEYAMBINC 

SOR$_KEYED 

SOR$_KEY_LEN 

SOR$_LRI_MISS 

SOR$_MISLENOFF 

SOR$_MISS_PARAM 

SOR$_MULTIDIM 

SOR$_NODUPEXC 

SOR$_NOTRECORD 

SOR$_NUM _ke y 

SOR$_OPENIN 

SOR$_OPENOUT 

SOR$_READERR 

SOR$_RTNERROR 

SOR$_SIGNCOMPQ 

SOR$_SORT_ON 

SOR$_SPCIVC 

SOR$_SPCIVD 

SOR$_SPCIVF 

SOR$_SPCIVI 

SOR$_SPCIVK 

SOR$_SPCIVP 

SOR$_SPCIVS 


CDD error at node 'name'. 

Error closing 'file' as input. 

Error closing 'file' as output. 

Invalid character definition. 

Collating sequence is too complex. 

Invalid pad character. 

Cannot define 3-byte collating values. 

Completed with diagnostics. 

Nondecimal base is invalid. 

Record containing symbolic literals is unsupported. 
Nonzero scale invalid for floating-point data-item. 

Number of digits is not consistent with the type or 
length of item. 

Include specification references no data, at line n. 
Include specification references no keys, at line n. 
Indexed output file must already exist. 

Key specification is ambiguous or inconsistent. 

Mismatch between sort/merge keys and primary 
file key. 

Invalid key length, key number n, length n. 

Longest record length must be specified. 

Length and offset required. 

A required subroutine argument is missing. 

Invalid multidimensional OCCURS. 

Equal-key routine and no-duplicates option cannot 
both be specified. 

Node 'name' is a 'name', not a record definition. 
Too many keys specified. 

Error opening 'file' as input. 

Error opening 'file' as output. 

Error reading 'file'. 

Unexpected error status from user-written routine. 

Absolute Date and Time datatype represented in 
one second units. 

Sort or merge routines called in incorrect order. 
Invalid collating sequence specification at line n. 
Invalid data type at line n. 

Invalid field specification at line n. 

Invalid include or omit specification at line n. 

Invalid key or data specification at line n. 

Invalid sort process at line n. 

Invalid specification at line n. 
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SOR$_SPCIVX 

SOR$_SPCMIS 

SOR$_SPCOVR 

SORS—SPCSIS 

SOR$_SRTIWA 

SOR$_ST ABLEEX 

SOR$_SYSERROR 

SOR$_UNDOPTION 

SOR$_UNSUPLEVL 

SOR$_WRITEERR 


Invalid condition specification at line n. 

Invalid merge specification at line n. 

Overridden specification at line n. 

Invalid sort specification at line n. 

Insufficient space; specification file is too complex. 

Equal-key routine and stable option cannot both be 
specified. 

System service error. 

Undefined option flag was set. 

Unsupported core level for record 'name'. 

Error writing 'file'. 
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SOR$BEGII\l_SORT—Begin a Sort 

Operation 



Initializes a sort operation by opening input and output files and by 
passing the key information and any sort options. 

FORMAT 

SORSBEGIN-SORT [key-buffer][,lrl][,options] 

[, file—alloc] [, user—compare] 
[,user— equal] [,sort—process] 

[, work— files] [, context] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

key—buffer 

VMS Usage: vector_word_unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Array of words describing the key(s) on which you plan to sort. The 
key-buffer argument is the address of an array containing the key 
description(s). 

The first word of this array contains the number of keys described (up to 
255). Following the first word, each key is described (in order of priority) 
in blocks of four words. The four words specify the key's data type, order, 
offset, and length, respectively. 

The first word of the block specifies the data type of the key. The following 
data types are accepted: 

DSC$K_DTYPE_Z Unspecified (uninfluenced by collating sequence) 

DSC$K_DTYPE_B Byte integer (signed) 

DSC$K_DTYPE_BU Byte (unsigned) 

DSC$K_DTYPE_W Word integer (signed) 

DSC$K_DTYPE_WU Word (unsigned) 

DSC$K_DTYPE_L Longword integer (signed) 

DSC$K_DTYPE_LU Longword (unsigned) 

DSC$K_DTYPE_Q Quadword integer (signed) 
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DSC$K_DTYPE_QU 

DSC$K_DTYPE_0 

DSC$K_DTYPE_OU 

DSC$K_DTYPE_F 

DSC$K_DTYPE_D 

DSC$K_DTYPE_G 

DSC$K_DTYPE_H 

DSC$K_DTYPE_T 

DSC$K_DTYPE_NU 

DSC$K_DTYPE_NL 

DSC$K_DTYPE_NLO 

DSC$K_DTYPE_NR 

DSC$K_DTYPE_NRO 

DSC$K_DTYPE_NZ 

DSC$K_DTYPE_P 


Quadword (unsigned) 

Octaword integer (signed) 

Octaword (unsigned) 

Single-precision floating 
Double-precision floating 
G-format floating 
H-format floating 

Text (may be influenced by collating sequence) 
Numeric string, unsigned 
Numeric string, left separate sign 
Numeric string, left overpunched sign 
Numeric string, right separate sign 
Numeric string, right overpunched sign 
Numeric string, zoned sign 
Packed decimal string 


The VAX Procedure Calling and Condition Handling Standard, documented 
in Section 2 in the Introduction to VAX /VMS System Routines , describes each 
of these data types. 

The second word of the block specifies the key order, 0 for ascending order, 1 
for descending order. The third word of the block specifies the relative offset 
of the key in the record. Note that the first byte in the record is at position 
0. The fourth word of the block specifies the key length in bytes (in digits for 
packed decimal—DSC$K_DTYPE_P). 

The key buffer address argument specifies the address of the key buffer in the 
data area. If you do not specify this argument, you must either pass a key 
comparison routine or use a specification file to define the key. 


Irl 

VMS Usage: 
type: 
access: 
mechanism: 


word-unsigned 
word (unsigned) 
read only 
by reference 


Length of the longest record that will be released for sorting. The lrl 
argument is the address of a word containing the length. This argument 
is not required if the input file(s) is on disk, but is required when you use the 
record interface. For VFC records, this length must include the length of the 
fixed-length portion of the record. 


options 

VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Flags that identify sort options. The options argument is the address of a 
longword bit mask whose settings determine the merge options selected. The 
bit mask values available are as follows: 
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Flags 

Description 

SOR$M _ST ABLE 

Keeps records with equal keys in the same order in which 
they appeared on input. With multiple input files that have 
records that collate as equal, records from the first input 
file are placed before the records from the second input 
file, and so on. 

SOR$M_EBCDIC 

Orders ASCII character keys according to EBCDIC collating 
sequence. No translation takes place. 

SOR$M_MULTI 

Orders character keys according to the multinational 
collating sequence, which collates the international 
character set. 

SOR$M_NOSIGNAL 

Returns the condition code instead of signalling an error. 
SOR$M—NOSIGNAL is the default. 

SOR$M_NODUPS 

Omits records with duplicate keys. You cannot use this 
option if you specify your own equal-key routine. 


All other bits in the longword are reserved and must be zero. 


file—alloc 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Input file size in blocks. The file—alloc argument is the address of a longword 
containing the size. This argument is never required because by default, 
SORT uses the allocation of the input files. If you are using the record 
interface or if the input files are not on disk, the default is 1000 blocks. 

However, you can use this optional argument to improve the efficiency of the 
sort by adjusting the amount of resources the sort process allocates. 


user—compare 

VMS Usage: procedure 
type: procedure entry mask 

access: function call 

mechanism: by reference 


Routine that compares records to determine their sort order. The 
user_compare argument is the address of the entry mask for this user-written 
routine. This argument is required if you do not specify the key_buffer 
argument, or if you define key information in a specification file. 

SORT/MERGE calls the comparison routine with five reference arguments— 
ADRS1, ADRS2, LENG1, LENG2, CNTX—the addresses of the two records 
to be compared, the lengths of these two records, and the context longword. 

The comparison routine must return a 32-bit integer value: 

• -1 if the first record collates before the second 


• 0 if the records collate as equal 

• 1 if the first record collates after the second 
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user—equal 


VMS Usage: 
type: 
access: 
mechanism: 


procedure 

procedure entry mask 
function call 
by reference 


Routine that resolves the sort order when records have duplicate keys. 

The user—equal argument is the address of the entry mask for this user- 
written routine. Do not use this argument if you specify SOR$M—STABLE or 
SOR$M_NODUPS in the options argument. 

SORT/MERGE calls the duplicate key routine with five reference 
arguments—ADRS1, ADRS2, LENG1, LENG2, CNTX—the addresses of 
the two records that compare equally, the lengths of the two records that 
compare equally, and the context longword. 

The routine must return a 32-bit integer condition code: 


Code 

SOR$_DELETE1 

SOR$_DELETE2 

SOR$_DELBOTH 

SS$_NORMAL 


Description 

Delete the first record from the sort 
Delete the second record from the sort 
Delete both records from the sort 
Keep both records in the sort 


Any other failure value causes the error to be signaled or returned. Any other 
success value causes an undefined result. 


sort—process 


VMS Usage: 
type: 
access: 
mechanism: 


byte_unsigned 
byte (unsigned) 
read only 
by reference 


Type of sort process. The sort—process argument is the address of a byte 
whose value indicates whether the sort type is record, tag, index, or address. 
The default is record. If you select the record interface on input, you can use 
only a record sort process. 

Specify a byte containing the value for the type of sort process you want: 

• SOR$GK_RECORD (record sort) 

• SOR$GK_TAG (tag sort) 

• SOR$GK_ADDRESS (address sort) 

• SOR$GK—INDEX (index sort) 


work—files 


VMS Usage: 
type: 
access: 
mechanism: 


byte—unsigned 
byte (unsigned) 
read only 
by reference 


Number of work files to be used in the sorting process. The work—files 
argument is the address of a byte containing the number of work files; 
permissible values range from 0 through 10. 
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By default, SORT creates two temporary work files when it needs them and 
determines their size from the size of your input file(s). You can increase 
the number of work files to reduce their individual size so that each will 
then fit into less disk space. You can also assign each of them to different 
disk-structured devices. 


context 

VMS Usage: 
type: 
access: 
mechanism: 


context 

longword (unsigned) 
write only 
by reference 


Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for 
the same operation, you must pass the context value that was supplied by 
SORT/MERGE. 


DESCRIPTION The SOR$BEGIN_SORT initializes the sort process by setting up sort work 

areas and provides key specification and sort options. 

Specify the key information with the key buffer argument, the user_compare 
argument, or in a specification file. If no key information is specified, the 
default (character for the entire record) is used. 

You must use the SOR$BEGIN_SORT routine to initialize the sort process for 
the file, record, and mixed interfaces. For record interface on input, you must 
use the longest record length argument. 

Some of the following values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 


CONDITION 

SS$_NORMAL 

Success. 

VALUES 

SOR$_BADLOGIC 

Internal logic error detected. 

RETURNED 

SOR$_BAD_KEY 

Invalid key specification. 


SOR$_BAD_LRL 

Record length n greater than specified longest 
record length. 


SOR$_BAD_MERGE 

Number of work files must be between 0 and 10. 


SOR$_BAD_TYPE 

Invalid sort process specified. 


SOR$_ENDDIAGS 

Completed with diagnostics. 


SOR$_INSVIRMEM 

Insufficient virtual memory. 


SOR$_KEYAMBINC 

Key specification is ambiguous or inconsistent. 


SOR$_KEY_LEN 

Invalid key length, key number n, length n. 


SORS—LRI_MISS 

Longest record length must be specified. 


SORS—NODUPEXC 

Equal-key routine and no-duplicates option cannot 
both be specified. 
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SOR$_NUM_KEY 
SOR$_RTNERROR 
SOR$_SORT_ON 
SOR$_ST ABLEEXC 

SOR$_SYSERROR 

SOR$_UNDOPTION 


Too many keys specified. 

Unexpected error status from user-written routine. 
Sort or merge routines called in incorrect order. 

Equal-key routine and stable option cannot both be 
specified. 

System service error. 

Undefined option flag was set. 
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SOR$END. 

.SORT—End a Sort Operation 

Does cleanup functions, such as closing files and releasing memory. 

FORMAT 

SOR$END_SORT [context] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

context 

VMS Usage: context 
type: longword 

access: write only 

mechanism: by reference 

Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for 
the same operation, you must pass the context value that was supplied by 
SORT/MERGE. 

DESCRIPTION 

The SOR$END_SORT routine ends a sort or merge operation, either at the 
end of a successful process or between calls because of an error. If an error 
status is returned, you must call SOR$END_SORT to release all allocated 
resources. In addition, this routine may be called at any time to close files 
and release memory. 

The value of the optional context argument is cleared when the 
SOR$END_SORT routine completes its operation. 

Some of the following values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, you should use 

LIB$MATCH_COND if you want to check for a specific status. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SORS—CLOSEIN 

SOR$_CLOSEOUT 

SOR$_ENDDIAGS 

SOR$_END_SORT 

SOR$_SYSERROR 


Success. 

Error closing 'file' as input. 

Error closing 'file' as output. 

Completed with diagnostics. 

Sort/merge terminated, context = 'context'. 
System service error. 
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SOR$PASS_FILES—Pass File Names 



Passes the names of input and output files and output file 
characteristics to SORT or MERGE. 

FORMAT 

SOR$PASS—FILES [inp—desc] [, out—desc]],org] 

[, rfm] [, bks] [, bis] [, mrs] [, alq] 

[, fop] [, fsz] ], context] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

inp—desc 

VMS Usage: char_string 
type: character-coded text string 

access: read only 

mechanism: by descriptor 

Input file specification. The inp_desc argument is the address of a descriptor 
pointing to the file specification. In the file interface, you must call 
SOR$PASS_FILES to pass SORT the input file specification(s). For multiple 
input files, call SOR$PASS_FILES once for each input file, passing one input 
file specification descriptor each time. 

In the mixed interface, if you are using the record interface on input, pass 
only the output file specification; do not pass any input file specification(s). 

If you are using the record interface on output, pass only the input file 
specification(s); do not pass an output file specification or any of the optional 
output file arguments. 

out—desc 

VMS Usage: char_string 
type: character-coded text string 

access: read only 

mechanism: by descriptor 

Output file specification. The out_desc argument is the address of a 
descriptor pointing to the file specification. In the file interface, when you 
call SOR$PASS_FILES, you must pass the output file specification. Specify 
the output file specification and characteristics only once, as part of the first 
call. 

Call SOR$PASS_FILES(Input1,Output) 

Call S0R$PASS_FILES(Input2) 

Call S0R$PASS_FILES(Input3) 
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In the mixed interface, if you are using the record interface on input, pass 
only the output file specification; do not pass any input file specifications. 

If you are using the record interface on output, pass only the input file 
specification(s); do not pass an output file specification or any of the optional 
output file arguments. 


org 

VMS Usage: 
type: 
access: 
mechanism: 


byte_unsigned 
byte (unsigned) 
read only 
by reference 


File organization of the output file, if different from the input file. The org 
argument is the address of a byte whose value specifies the organization of 
the output file; permissible values include: 


FAB$C_SEQ 

FAB$C_REL 

FAB$C_IDX 


For the record interface on input, the default value is sequential. For the file 
interface, the default value is the file organization of the first input file for 
record or tag sort and sequential for address and index sort. 

For more information on the FAB fields, see the VAX Record Management 
Services Reference Manual. 


rfm 

VMS Usage: 
type: 
access: 
mechanism: 


byte_unsigned 
byte (unsigned) 
read only 
by reference 


Record format of the output file, if different from the input file. The rfm 
argument is the address of a byte whose value specifies the record format of 
the output file; permissible values include: 


FAB$C_FIX 

FAB$C_VAR 

FAB$C_VFC 


For the record interface on input, the default value is variable. For the file 
interface, the default value is the record format of the first input file for record 
or tag sort and fixed format for address or index sort. For the mixed interface 
with record interface on input, the default value is variable format. 


bks 

VMS Usage: 
type: 
access: 
mechanism: 


byte_unsigned 
byte (unsigned) 
read only 
by reference 


Bucket size of the output file, if different from the first input file. The bks 
argument is the address of a byte that contains this size. Use this argument 
with relative and indexed-sequential files only. If the bucket size of the 
output file is to differ from that of the first input file, specify a byte to indicate 
the bucket size. Acceptable values are from 1 to 32 . If you do not pass this 
argument—and the output file organization is the same as that of the first 
input file—the bucket size defaults to the value of the first input file. If the 
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file organizations differ or if the record interface is used on input, the default 
value is 1 block. 


bis 

VMS Usage: 
type: 
access: 
mechanism: 


word—unsigned 
word (unsigned) 
read only 
by reference 


Block size of a magnetic tape output file. The bis argument is the address of 
• a word that contains this size. Use this argument with magnetic tapes only. 
Permissible values range from 20 to 65,532. However, to ensure compatibility 
with non-DIGITAL systems, ANSI standards require that the block size be 
less than or equal to 2048. 

The block size defaults to the block size of the input file tape. If the input file 
is not on tape, the output file block size defaults to the size used when the 
tape was mounted. 


mrs 

VMS Usage: 
type: 
access: 
mechanism: 


word—unsigned 
word (unsigned) 
read only 
by reference 


Maximum record size for the output file. The mrs argument is the address 
of a word that specifies this size. The following table contains acceptable for 
each type of file. 


File Organization 

Acceptable Value 

Sequential 

0 to 32,767 

Relative 

0 to 16,383 

Indexed sequential 

0 to 16,362 


SORT will not check maximum record size if you omit this argument, or if 
you specify a value of 0 . 

If this argument is not specified, the default is based on the output file 
organization and format unless the organization is relative or the format 
is fixed. The longest output record length is based on the calculated input 
longest record length, the type of sort, and the record format. 


alq 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Number of preallocated output file blocks. The alq argument is the address 
of a longword that specifies the number of blocks you want to preallocate to 
the output file. Acceptable values are from 1 to 4,294:,967,295 . 

Pass this argument if you know that your output file allocation will be larger 
or smaller than that for your input file(s). The default value is the total 
allocation of all the input files. If the allocation cannot be obtained for any 
of the input files or if record interface is used on input, the file allocation 
defaults to 1000 blocks. 
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fop 

VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


File-handling options. The fop argument is the address of a longword whose 
bit settings determine the options selected. For a list of valid options, see the 
description of the FAB$L_FOP field in the VAX Record Management Services 
Reference Manual. By default, only the DFW (deferred write) option is set. If 
your output file is indexed, you should set the CIF option (create if). 


fsz 

VMS Usage: 
type: 
access: 
mechanism: 


byte_unsigned 
byte (unsigned) 
read only 
by reference 


Size of the fixed portion of VFC records. The fsz argument is the address of a 
byte containing this size. If you do not pass this argument, the default is the 
size of the fixed portion of the first input file. If you specify the VFC size as 
0, RMS defaults the value to 2 bytes. 


context 

VMS Usage: 
type: 
access: 
mechanism: 


context 

longword (unsigned) 
write only 
by reference 


Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for 
the same operation, you must pass the context value that was supplied by 
SORT/MERGE. 


DESCRIPTION The SOR$PASS_FILES routine passes input and output file specifications to 
SORT. The SOR$PASS_FILES routine must be repeated for multiple input 
files. The output file name string and characteristics should be specified in 
only the first call to SOR$PASS_FILES. 

This routine also accepts optional arguments that specify characteristics for 
the output file. By default, the output file characteristics are the same as the 
first input file; specified output file characteristics are used to change these 
defaults. 

Some of the following values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SOR$_DUP_OUTPUT 

SOR$_ENDDIAGS 

SOR$_INP_FILES 

SOR$_SORT_ON 

SORS—SYSERROR 


Success. 

Output file has already been specified. 
Completed with diagnostics. 

Too many input files specified. 

Sort or merge routines called in incorrect order. 
System service error. 
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SOR$RELEASE_REC—Pass One Record to 

Sort 



Used with the record interface to pass one input record to SORT or 
MERGE. 

FORMAT 

SOR$RELEASE_REC desc [,context] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

desc 

VMS Usage: char_string 
type: character-coded text string 

access: read only 

mechanism: by descriptor 

Input record buffer. The desc argument is the address of a descriptor 
pointing to the buffer containing the record to be sorted. If you use the 
record interface, this argument is required. 

context 

VMS Usage: context 
type: longword 

access: modify 

mechanism: by reference 

Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for 
the same operation, you must pass the context value that was supplied by 
SORT/MERGE. 

DESCRIPTION 

Call SOR$RELEASE__REC to pass records to SORT or MERGE with the 
record interface. SOR$RELEASE_REC must be called once for each record to 
be sorted. 

Some of the following values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 
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CONDITION SSS—NORMAL 

VALUES SOR$_BADLOGIC 

RETURNED sor$_b ad_lrl 

SOR$_BAD_SRL 

SOR$_ENDDIAGS 

SOR$_EXTEND 

SOR$_MISS_PARAM 

SOR$_NO_WRK 

SOR$_OPENOUT 

SOR$_OPERFAIL 

SOR$_OPREPLY 

SOR$_READERR 

SOR$_REQ_ALT 

SOR$_RTNERROR 

SOR$_SORT_ON 

SORS—SYSERROR 

SOR$_USE_ALT 

SOR$_WORK_DEV 


Success. 

Internal logic error detected. 

Record length n greater than specified longest 
record length. 

Record length n is too short to contain keys. 
Completed with diagnostics. 

Unable to extend work file for needed space. 

The desc argument is missing. 

Work files required, cannot do sort in memory as 
requested. 

Error opening 'file' as output. 

Error requesting operator service. 

Operator reply is "reply". 

Error reading 'file'. 

Specify alternate 'name' file (or nothing to simply 
try again). 

Unexpected error status from user-written routine. 
Sort or merge routines called in incorrect order. 
System service error. 

Using alternate file 'name 7 . 

Work file 'name 7 must be on random access local 
device. 
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SOR$RETURN_REC—Return One Sorted 

Record 



Used with the record interface to return one sorted or merged 
record to a program. 

FORMAT 

SOR$RETURN_REC desc[,length][^context] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

desc 

VMS Usage: char_string 
type: character-coded text string 

access: write only 

mechanism: by descriptor 

Output record buffer. The desc argument is the address of a descriptor 
pointing to the buffer that receives the sorted or merged record. 

length 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Length of the output record. The length argument is the address of a word 
that receives the length of the record returned from SORT/MERGE. 

context 

VMS Usage: context 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for 
the same operation, you must pass the context value that was supplied by 
SORT/MERGE. 
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DESCRIPTION Call the SOR$RETURN_REC routine to release the sorted or merged records 

to a program. Call this routine once for each record to be returned. 

SOR$RETURN_REC places the record into a record buffer that you set up in 
the program's data area. After SORT has successfully returned all the records 
to the program, it returns the status code SS$_ENDOFFILE, which indicates 
that there are no more records to return. 

Some of the following values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 


CONDITION SS$_NORMAL 

VALUES SOR$_BADLOGIC 

RETURNED sor$_enddiags 

SOR$_EXTEND 

SOR$_MISS_PARAM 

SOR$_OPERFAIL 

SOR$_OPREPLY 

SOR$_READERR 

SOR$_REQ_ALT 

SOR$_RTNERROR 

SOR$_SORT_ON 

SOR$_SYSERROR 

SOR$_USE_ALT 

SOR$_WORK_DEV 


Success. 

Internal logic error detected. 

Completed with diagnostics. 

Unable to extend work file for needed space. 

A required subroutine argument is missing. 

Error requesting operator service. 

Operator reply is "reply". 

Error reading 'file 7 . 

Specify alternate 'name' file (or nothing to simply 
try again). 

Unexpected error status from user-written routine. 
Sort or merge routines called in incorrect order. 
System service error. 

Using alternate file 'name'. 

Work file 'name 7 must be on random access local 
device. 
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SOR$SORT_MERGE—Sort 



Sorts the input records. 

FORMAT 

SOR$SORT_MERGE [context] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

\ 

ARGUMENT 

context 

VMS Usage: context 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for 
the same operation, you must pass the context value that was supplied by 
SORT/MERGE. 

DESCRIPTION 

After you have passed either the file names or the records to SORT, call the 
SOR$SORT_MERGE routine to sort the records. For file interface on input, 
the input files are opened and the records are released to the sort. For the 
record interface on input, the record must have already been released (by 
calls to SOR$RELEASE_REC). For file interface on output, the output records 
are reformatted and directed to the output file. For the record interface on 
output, SOR$RELEASE_REC must be called to get the sorted records. 

Some of the return values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Success. 

SOR$_BADDTYPE Invalid or unsupported CDD datatype. 

SOR$_BADLENOFF Length and offset must be multiples of 8 bits. 

SOR$_BADLOGIC Internal logic error detected. 
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SOR$_BADOCCURS 

SOR$_BADOVRLAY 

SOR$_BADPROTCL 

SOR$_BAD_LRL 

Invalid OCCURS clause. 

Invalid overlay structure. 

Node is an invalid CDD object. 

Record length n greater than specified longest 
record length. 

SOR$_BAD_TYPE 

SOR$_CDDERROR 

SOR$_CLOSEIN 

SOR$_CLOSEOUT 

SOR$_COI_CHAR 

SORS—COI_CMPLX 

SOR$_COI_PAD 

SOR$_COL-THREE 

SOR$_ENDDIAGS 

SOR$_EXTEND 

SOR$_ILLBASE 

SOR$_ILLLITERL 

SOR$_ILLSCALE 

SOR$_INCDIGITS 

Invalid sort process specified. 

CDD error at node 'name'. 

Error closing 'file' as input. 

Error closing 'file' as output. 

Invalid character definition. 

Collating sequence is too complex. 

Invalid pad character. 

Cannot define 3-byte collating values. 

Completed with diagnostics. 

Unable to extend work file for needed space. 

Nondecimal base is invalid. 

Record containing symbolic literals is unsupported. 
Nonzero scale invalid for floating-point data-item. 

Number of digits is not consistent with the type or 
length of item. 

SORS—INCNOD AT A 

SOR$_INCNOKEY 

SOR$_IND—OVR 

SOR$_KEYED 

Include specification references no data, at line n. 
Include specification references no keys, at line n. 
Indexed output file must already exist. 

Mismatch between sort/merge keys and primary 
file key. 

SOR$_LRL _MISS 

SOR$_MISLENOFF 

SOR$_MULTIDIM 

SORS-NOTRECORD 

SOR$_NO_WRK 

Longest record length must be specified. 

Length and offset required. 

Invalid multidimensional OCCURS. 

Node 'name' is a 'name', not a record definition. 

Work files required, cannot do sort in memory as 
requested. 

SOR$_OPENIN 

SOR$_OPENOUT 

SOR$_OPERFAIL 

SOR$_OPREPLY 

SOR$_READERR 

SOR$_REQ_ALT 

Error opening 'file' as input. 

Error opening 'file' as output. 

Error requesting operator service. 

Operator reply is “reply". 

Error reading 'file'. 

Specify alternate 'name' file (or nothing to simply 
try again). 

SOR$_RTNERROR 

SOR$_SIGNCOMPQ 

Unexpected error status from user-written routine. 

Absolute Date and Time datatype represented in 
one second units. 

SOR$_SORT—ON 

SOR$_SPCIVC 

Sort or merge routines called in incorrect order. 
Invalid collating sequence specification, at line n. 


SOR—45 









Sort/Merge (SOR) Routines 

SOR$SORT_MERGE 


SOR$_SPCIVD 

SOR$_SPCIVF 

SOR$_SPCIVI 

SOR$_SPCIVK 

SOR$_SPCIVP 

SOR$_SPCIVS 

SOR$_SPCIVX 

SOR$_SPCMIS 

SOR$_SPCOVR 

SOR$_SPCSIS 

SOR$_SRTIWA 

SOR$_SYSERROR 

SOR$_UNSUPLEVL 

SOR$_USE _ALT 

SOR$_WORK_DEV 

Invalid data type, at line n. 

Invalid field specification, at line n. 

Invalid include or omit specification, at line n. 

Invalid key or data specification, at line n. 

Invalid sort process, at line n. 

Invalid specification, at line n. 

Invalid condition specification, at line n. 

Invalid merge specification, at line n. 

Overridden specification, at line n. 

Invalid sort specification, at line n. 

Insufficient space; specification file is too complex 

System service error. 

Unsupported core level for record 'name'. 

Using alternate file 'name'. 

Work file 'name' must be on random access local 
device. 

SOR$_WRITEERR 

Error writing 'file'. 
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SOR$SPEC_FILE—Pass a Specification 

File Name 

Used to pass a specification file or specification text. 


FORMAT SOR$SPEC_FILE [spec-file][,spec-buffer] 

[, context] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 


"CONDITION VALUES RETURNED." 


ARGUMENTS 


spec—file 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 

read-only 

by descriptor 


Specification file name. The spec_file argument is the address of a descriptor 
pointing to the name of a file that contains the text of the options requested 
for the sort or merge. The specification file name string and the specification 
file buffer arguments are mutually exclusive. 


spec—buffer 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 

character-coded text string 

read-only 

by descriptor 


Specification text buffer. The spec-buffer argument is the address of a 
descriptor pointing to a buffer containing specification text. This text has the 
same format as the text within the specification file. The specification file 
name string and the specification file buffer arguments are mutually exclusive. 


context 

VMS Usage: 
type: 
access: 
mechanism: 


context 

longword (unsigned) 

modify 

by reference 


Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
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the operation just initiated. When you make subsequent routine calls for 
the same operation, you must pass the context value that was supplied by 
SORT/MERGE. 

DESCRIPTION 

Call SOR$SPEC_FILE to pass a specification file name or a buffer with 
specification text to a sort or merge operation. Through the use of a 
specification file, you may selectively omit or include particular records 
from the sort or merge operation and specify the reformatting of the output 
records. (See the Sort Utility in the VAX/VMS Sort/Merge Utility Reference 
Manual for a complete description of specification files.) 

If you call the SOR$SPEC_FILE routine, you must do so before you call any 
other routines. You must pass either the spec... file or spec_buffer argument, 
but not both. 

Some of the return values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 

CONDITION 

VALUES 

RETURNED 

SORS—ENDDIAGS Completed with diagnostics. 

SOR$_SORT_ON Sort or merge routines called in incorrect order. 

SORS—SYSERROR System service error. 
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SOR$STAT—Obtain a Statistic 

Returns one statistic about the sort or merge operation to the user 
program. 

FORMAT 

SOR$STAT code,result[,context] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

code 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

SORT/MERGE statistic code. The code argument is the address of a word 
containing the code that identifies the statistic you want returned in the result 
argument. The following values are accepted: 


Code 

Description 

SOR$K_IDENT 

Address of ASCII string for version number 

SOR$K_REC_INP 

Number of records input 

SOR$K_REC_SOR 

Records sorted 

SOR$K_REC_OUT 

Records output 

SOR$K_LRI_INP 

LRL for input 

SOR$K_LRI_INT 

Internal LRL 

SOR$K_LRI_OUT 

LRL for output 

SOR$K_NODES 

Nodes in sort tree 

SOR$K_INI _RUNS 

Initial dispersion runs 

SOR$K_MRG_ORDER 

Maximum merge order 

SOR$K_MRG_P ASSES 

Number of merge passes 

SOR$K_WRK—ALQ 

Work file allocation 

SOR$K_MBC_INP 

Multiblock count for input 

SOR$K _MBC—OUT 

Multiblock count for output 

SORSK—MBF—INP 

Multibuffer count for input 

SOR$K_MBF_OUT 

Multibuffer count for output 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


Note that performance statistics (such as direct I/O, buffered I/O, and elapsed 
and CPU times) are not available because user-written routines may affect 
those values. However, they are available by calling LIB$GETJPI. 


result 

VMS Usage: 
type: 
access: 
mechanism: 


longword_unsigned 
longword (unsigned) 
write only 
by reference 


SORT/MERGE statistic value. The result argument is the address of a 
longword into which SORT/MERGE writes the value of the statistic identified 
by the code argument. 


context 

VMS Usage: 
type: 
access: 
mechanism: 


context 

longword (unsigned) 

modify 

by reference 


Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for 
the same operation, you must pass the context value that was supplied by 
SORT/MERGE. 


The SOR$STAT routine returns one statistic about the sort or merge operation 
to your program. You can call the SOR$STAT routine at any time while the 
sort or merge is active. 

Some of the following values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 


SOR$_ENDDIAGS 

SOR$_MISS_PARAM 

SOR$_NYI 

SOR$_SYSERROR 


Completed with diagnostics. 

A required subroutine argument is missing. 
Functionality is not yet implemented. 
System service error. 
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Introduction to VAXTPU Routines 

Callable VAXTPU makes VAXTPU accessible from within other VAX 
languages and applications. VAXTPU can be called from a program written 
in any VAX language that generates calls using the VAX/VMS Procedure 
Calling and Condition Handling Standard. You can also call VAXTPU from 
VAX/VMS utilities, for example, MAIL. Callable VAXTPU allows you to 
perform text processing functions within your program. 

Callable VAXTPU consists of a set of callable routines that resides in the 
VAXTPU shareable image, TPUSHR.EXE. You access callable VAXTPU by 
linking against this shareable image, which includes the callable interface 
routine names and constants. As with the DCL-level VAXTPU interface, you 
can use files for input to and output from callable VAXTPU. You can also 
write your own routines for processing input, output, and messages. 

This section describes callable VAXTPU. It describes the purpose of the 
VAXTPU callable routines, the parameters for the routine call, and the 
primary status returns. The parameter in the call syntax represents the object 
that you pass to a VAXTPU routine. Each parameter description lists the data 
type and the passing mechanism for the object. The data types are standard 
VAX/VMS data types. The passing mechanism indicates how the parameter 
list is interpreted. 

This section is written for systems programmers and it assumes that you are 
familiar with the following: 

• The VAX/VMS Procedure Calling and Condition Handling Standard 

• The VAX/VMS Run-Time Library (RTL) 

• The precise manner in which data types are represented on a VAX 
computer 

• The method for calling routines written in a language other than the one 
you are using for the main program 

The calling program must ensure that parameters passed to a called 
procedure, in this case VAXTPU, are of the type and form that the VAXTPU 
procedure accepts. 
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12.1.1 Two Interfaces to Callable VAXTPU 

There are two ways in which you can access callable VAXTPU: the simplified 
callable interface and the full callable interface. 

Simplified Callable Interface 

The easiest way to use callable VAXTPU is to use the simplified callable 
interface. VAXTPU provides two alternative routines in its simplified callable 
interface. These routines in turn call additional routines that do the following: 

• Initialize the editor 

• Provide the editor with the parameters necessary for its operation 

• Control the editing session 

• Perform error handling 

When using this simplified form of callable VAXTPU, you can use the 
TPU$TPU routine to specify a VAX/VMS command line for VAXTPU, or 
you can call the TPU$EDIT routine to specify an input file and an output 
file. TPU$EDIT builds a command string that is then passed to the TPU$TPU 
routine. These two routines are described in detail in Section 12.2, The 
Simplified Callable Interface. 

Full Callable Interface 

Another way to use callable VAXTPU is to have your program directly access 
the main callable VAXTPU routines. These routines do the following: 

• Initialize the editor (TPU$INTIALIZE) 

• Execute VAXTPU procedures (TPU$EXECUTE_INIFILE and 
TPU$EXECUTE —COMMAND) 

• Control the editor (TPU$CONTROL) 

• Terminate the calling session (TPU$CLEANUP) 

When using callable VAXTPU in this way, you must provide values for certain 
parameters. In some cases, the values that you supply are actually addresses 
for additional routines. For example, when you call TPU$INITIALIZE, you 
must include the address of a routine that specifies initialization options. 
Depending on your particular application, you may also have to write 
additional routines. For example, you may need to write routines for 
performing file operations, handling errors, and otherwise controlling the 
editing session. Callable VAXTPU provides utility routines that can perform 
some of these tasks for you. These utility routines can do the following: 

• Parse the VAX/VMS command line and build the item list used for 
initializing the editor 

• Handle file operations 

• Write error messages 

• Handle conditions 
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Various topics relating to the full callable interface are discussed in the 
following sections: 

• Section 12.3, The Full Callable Interface, begins by briefly describing the 
interface. However, most of this section is devoted to a description of the 
main callable VAXTPU routines (TPU$INITIALIZE, TPU$EXECUTE_ 
INIFILE, TPU$CONTROL, TPU$EXECUTE-COMMAND, and 
TPU$CLEANUP). 

• Section 12.3.2, Other VAXTPU Utility Routines, discusses additional 
routines that VAXTPU provides for use with the full callable interface. 

• Section 12.3.3, User-Written Routines, defines the requirements for 
routines that you can write for use with the full callable interface. 

The full callable interface consists of the main callable VAXTPU routines and 
the VAXTPU utility routines. Note that these routines are not visible to you 
when you use the simplified interface. 


12.1.2 Shareable Image 

Whether you use the simplified callable interface or the full callable interface, 
you access callable VAXTPU by linking against the VAXTPU shareable image, 
TPUSHR.EXE. This image contains the routine names and constants that are 
available for use by an application. In addition, TPUSHR.EXE provides the 
following symbols: 

• TPU$VERSION—the version of the shareable image. 

• TPU$UPDATE—the update number of the shareable image. 

• TPU$FACILITY—the VAXTPU facility number. 

For more information on how to link to the shareable image TPUSHR.EXE, 
refer to the VAX/VMS System Services Reference Manual. 


12.1.3 Passing Parameters to Callable VAXTPU Routines 

Parameters are passed to callable VAXTPU by reference or by descriptor. 
When the parameter is a routine, the parameter is passed by descriptor as a 
bound procedure value (BPV) data type. 

A bound procedure value is a two-longword entity in which the first 
longword contains the address of a procedure entry mask, and the second 
longword is the environment value. See Figure TPU-1. The environment 
value is determined in a language-specific manner when the original bound 
procedure value is generated. When the bound procedure is called, the calling 
program loads the second longword into Rl. 
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Figure TPU-1 Bound Procedure Value 


NAME OF YOUR ROUTINE 


ENVIRONMENT 


ZK-4046-85 


12.1.4 Error Handling 

When you use the simplified callable interface, VAXTPU establishes its own 
condition handler, TPU$HANDLER, to handle all errors. When you use the 
full callable interface, there are three ways to handle errors: 

1 You can use VAXTPU's default condition handler, TPU$HANDLER. 

2 You can write your own condition handler to replace VAXTPU's default 
condition handler. 

3 You can write your own condition handler to process some of the errors 
and call TPU$HANDLER to process the rest. 

The default condition handler, TPU$HANDLER, is described in the routine 
description section of this chapter. Information about writing your own 
condition handler can be found in the Introduction to VAX/VMS System 
Routines. 


12.1.5 Return Values 


All VAXTPU condition codes are declared as universal symbols. Therefore, 
you automatically have access to these symbols when you link your program 
to the shareable image. VAXTPU returns the condition code value in RO. 
VAXTPU return codes can be found in the VAX Text Processing Utility 
Reference Manual. VAXTPU return codes and their messages are included 
in the VAX/VMS System Messages and Recovery Procedures Reference Manual. 

Additional information about condition codes is provided in the descriptions 
of callable VAXTPU routines found in subsequent sections. This information 
is provided under the heading "Possible Return Values," and indicates the 
values that are returned when the default condition handler is established. 


12.2 The Simplified Callable Interface 

The VAXTPU simplified callable interface consists of two routines: TPU$TPU 
and TPU$EDIT. These entry points to VAXTPU are useful for the following 
kinds of applications: 

• Applications that are able to specify all the editing parameters on a single 
command line 

• Applications that need to specify only an input file and an output file 


TPU—4 












VAX Text Processing Utility (VAXTPU) Routines 

The Simplified Callable Interface 


12.2.1 Example of the Simplified Interface 

The following example shows how the simplified interface might be used to 
call VAXTPU. 

/* Sample C program that calls VAXTPU. This program uses TPU$EDIT 
to provide the names of the input and output files, and TPU$TPU 
to pass a complete command line to the editor. */ 

♦include descrip 

int return.status; 

char command.line [100]; 

static $DESCRIPTOR(input_file,"infile.dat"); 
static $DESCRIPTOR(output_file,"outfile.dat"); 
static $DESCRIPT0R(command_de8c,command_line); 

static $DESCRIPTOR(first_part_de8C,"EDIT/TPU/NOJOURNAL/NOCOMMAND/OUTPUT="); 
static $DESCRIPTOR(space_desc," M ); 
main (argc,argv) 
int argc; 
char *argv[] ; 

/* Call the routine that accepts the name of the input and output file. */ 

/* This passes the name of the input file and output file to VAXTPU. */ 

/* These values are made available to VAXTPU procedures for processing. */ 

retum.status = TPU$EDIT(Ainput_f ile, &output_f ile) ; 
if (! retum.status) 
exit (retum.status); 

/* Now we build a command line and pass it to VAXTPU. */ 

/* Note that in this case we want to do more than just specify the */ 

/* file names. Our command also includes the /NOJOURNAL and /NOCOMMAND */ 

/* qualifiers. 

/* Concatenate all the command information into one string */ 

return_8tatus = STR$CONCAT(Acommand.desc, trt irst_part_desc,Aoutput_file, 
fespace.desc,&input_file); 
if (! retum_status) 
exit (retum.status) ; 

/* Now call VAXTPU */ 

retum.status = TPU$TPU(Acommand.desc) ; 
exit(return.status); 

> 

The following section contains detailed information about the routines called 
by the simplified interface. For example, there is information about the 
default parameters used when initializing the editor and when exiting the 
editor. 


12.3 The Full Callable Interface 

The VAXTPU full callable interface consists of a set of routines that you can 
use to perform the following tasks: 

• Specify initialization parameters 

• Control file input/output 

• Specify commands to be executed by the editor 

• Control how conditions are handled 

When you use the simplified callable interface, the preceding operations are 
performed automatically. The individual VAXTPU routines that perform 
these functions can be called from a user-written program and are known as 
VAXTPU's full callable interface. This interface has two sets of routines: the 
main VAXTPU callable routines and the VAXTPU utility routines. These 
VAXTPU routines, and your own routines that pass parameters to the 
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VAXTPU routines, are the mechanism that your application uses to control 
VAXTPU. 

This section describes the main callable routines, how parameters are passed 
to these routines, the VAXTPU utility routines, and the requirements of 
user-written routines. 


12.3.1 Main Callable VAXTPU Utility Routines 

The following callable VAXTPU routines are described in this section: 

• TPU$INITIALIZE 

• TPU$EXECUTE _INIFILE 

• TPU$CONTROL 

• TPU$EXECUTE-COMMAND 

• TPU$CLEANUP 

Note: Before calling any of these routines you must establish TPU$HANDLER 
or provide your own condition handler. See the routine description of 
TPU$HANDLER at the end of this chapter and the "VAX/VMS Condition 
Handling Standard" in the Introduction to VAX/VMS System Routines for 
information on establishing a condition handler. 


12.3.2 Other VAXTPU Utility Routines 

The full callable interface includes several other utility routines for which you 
can provide parameters. Depending on your application, you may be able to 
use these routines rather than writing your own routines. The following five 
VAXTPU utility routines are described in this section: 

• TPU$CLIPARSE—parses a command line and builds the item list for 
TPU$INITIALIZE. 

• TPU$PARSEINFO—parses a command and builds an item list for 
TPU$INITIALIZE. 

• TPU$FILEIO—the default file I/O routine. 

• TPU$MESSAGE—writes error messages and strings using the built-in 
procedure MESSAGE. 

• TPU$HANDLER—the default condition handler. 


12.3.3 User-Written Routines 

This section defines the requirements for user-written routines. When these 
routines are passed to VAXTPU, they must be passed as bound procedure 
values. (See Section 12.1.3 for a description of bound procedure values.) 
Depending on your application, you may have to write one or all of the 
following routines: 

• Routine for initialization callback—This is a routine that TPU$INITIALIZE 
calls to obtain values for initialization parameters. Instead of writing your 
own initialization callback routine, you can use the TPU$CLIPARSE or 
TPU$PARSEINFO utility routine. 
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• Routine for file I/O—This is a routine that handles file operations. Instead 
of writing your own file I/O routine, you can use the TPU$FILEIO utility 
routine. You cannot use this routine for journal file operations or for 
operations done by the built-in procedure SAVE. 

• Routine for condition handling—This is a routine that handles error 
conditions. Instead of writing your own condition handler, you can use 
the default condition handler, TPU$HANDLER. 

• Routine for the built-in procedure CALL_USER—This is a routine 
that is called by the built-in procedure CALL_USER. You can use this 
mechanism to cause your program to get control during an editing session. 


12.4 Examples of Using VAXTPU Routines 

The following examples use Callable VAXTPU. The examples are included 
in the manual for illustrative purposes only. DIGITAL does not assume 
responsibility for supporting this example. 
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Example TPU-1 Sample VAX BLISS Template for Callable 
VAXTPU 


! How to declare the VAXTPU routines 

external routine 

tpu$FILEIO, 
tpu$HANDLER, 
tpulINITIALIZE, 
tpu$EXECUTE_INIFILE, 
tpu|EXECUTE_COMMAND, 
tpu$C0NTR0L, 
tpulCLEANUP; 

! How to declare the VAXTPU literals 

external literal 

i 

! File I/O operation codes 
tpulk.close, 
tpu$k_clo8e_delete, 
tpu$k_open, 
tpu$k_get, 
tpu$k_put, 

i 

! File access codes 

tpulk.access, 
tpu$k_io, 
tpu$k_input, 
tpu$k_output, 

! 

! Item codes 

tpu$k_calluser, 
tpu$k_fileio, 
tpu$k_output!ile, 
tpu$k_sectionfile, 
tpu$k_commandfile, 
tpu|k_filename, 
tpu$k_j ournalfile, 
tpu$k_options, 

! 

! Mask for values in options 
tpu$m_recover, 
tpu$m_j ournal, 
tpu$m_read, 
tpu$m_command, 
tpu$m_create, 
tpu$m_section, 
tpu$m_display, 
tpu$m_output, 

i 

! Bit positions for values in options 
tpu$v_display, 
tpu$v_recover, 
tpulv_journal, 
tpulv.read, 
tpu$v_create, 
tpu$v_command, 
tpu$v_section, 
tpu$v_output, 


(Continued on next page) 
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Example TPU-1 (Cont.) Sample VAX BLISS Template for 

Callable VAXTPU 


! VAXTPU status codes 

tpu$_nofileaccess, 
tpu$_openin, 
tpu$_inviocode, 
tpu$_failure, 
tpu$_closein, 
tpu$_closeout, 
tpu$_readerr, 
tpu$_writeerr, 
tpu$_8uccess; 

own 

OPTIONS: bitvector [32]; 

! OPTIONS will be passed to VAXTPU 

GLOBAL ROUTINE top.level = 

BEGIN 

!++ 

! Main entry point of your program 
! -- 

! Your_initialization_routine must be declared as a BPV 

local BPV: vector[2,long] initial (TPU_INIT,0);! Procedure block 

! First establish the condition handler 

LIB$ESTABLISH (tpu$handler); 

! Call the intialization routine and pass it the address of the BPV 
! which has the address of your initialization routine (VAXTPU 
! calls this) 

tpu$initialize (BPV); 

! Use the following call if the options word passed to VAXTPU indicated that 
! an initialization file needs to be executed and/or the TPU$INIT_PROCEDURE 
! in the section file needs to be executed. 

tpu$execute_inifile(); 

! Let VAXTPU take over. 
tpu$control(); 

! To break out of VAXTPU, use call.user from within a VAXTPU program 
! Upon return from tpufcontrol, the editing session is done 
tpu$cleanup(); 

! Loop and start the sequence over or exit 
return tpu$_success; 

END; 

ROUTINE TPU.INIT = 

BEGIN 

i 

i -- 

own BPV: vector[2,long] initial (TPU_I0,O);! Procedure block 

bind 

OUTFILE.D = '/.ascid'OUTPUT.TPU 1 : block [8.byte] , 

COMFILE.D = ‘/.ascid'TPUINI.TPU' : block [8,byte] , 

SECFILEJ) = '/.ascid'SYS$LIBRARY:EDTSECINI.TPU$SECTION' : block [8.byte] . 
FILE.D = Xascid'FILE.TPU': block [8.byte]; 


(Continued on next page) 
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Example TPU-1 (Cont.) Sample VAX BLISS Template for 

Callable VAXTPU 


! Set VAXTPU options I want to enable 

OPTIONS [tpu$v_display] = 1; 

OPTIONS[tpu$v_section] = 1; 

OPTIONS[tpu$v_create] = 1; 

OPTIONS[tpu$v_command] = 1; 

OPTIONS[tpu$v_recover] = 0; 

OPTIONS[tpu$v_journal] = 0; 

OPTIONS[tpu$v_read] = 0; 

OPTIONS[tpu$v_output] = 1; 


begin IJust for BIND 

bind 

! Set up item list to pass back to VAXTPU to tell it what to do 
! VAXTPU calls me back later 
ITEMLIST = uplit byte ( 


!buffer length, item code. 


buffer address, return address 


word (4), word 
word (4), word 
word (0), word 
word (0), word 
word (0), word 
word (0), word 
long (0) ); 


(tpu$k_options), 
(tpu$k_fileio), 
(tpu$k_outputfile), 
(tpu$k_commandfile), 
(tpu$k_filename), 
(tpu$k_sectionfile), 


long (OPTIONS), 
long (BPV), 
long (OUTFILE.D), 
long (COMFILE.D), 
long (FILE_D), 
long (SECFILE.D), 


long (0), 
long (0), 
long (0), 
long (0), 
long (0), 
long (0), 


return ITEMLIST; 
end; 

END; ! End of routine TPU_INIT 


GLOBAL ROUTINE TPU.IO (P.OPCODE, FILE.BLOCK, DATA: ref block [.byte]) = 
BEGIN 

i 

! 

local 

item: ref block [3,long], ! Item list entry 

status; 


! Look at the opcode (operation) that VAXTPU wants me to perform 
! and if I don't want to do it, just call it back 
! if (..P.OPCODE NEQ tpu$k_open) 

! then 

! return (tpu$fileio (.p_opcode, .file_block, .data)); 

! 

! Else set what operation to do 

selectone ..P.OPCODE of 
set 

[tpu$k_open]: 

! Time to open a file 
| 

begin 

item = .data; ! Point to the FILENAME item list entry 

end; 

return tpu$_success; ! End of tpu$k_open 

end; 

[tpu$k_get]: ! If none exists, then no data 

! Time to read a record 
begin 
end; 

[tpu$k_put]: ! Time to write a record 

begin 

return tpu$_success; 

end; 


(Continued on next page) 


TPU-10 







VAX Text Processing Utility (VAXTPU) Routines 

Examples of Using VAXTPU Routines 


Example TPU-1 (Cont.) Sample VAX BLISS Template for 

Callable VAXTPU 


[tpu$k_clo8e]: ITime to close a file 

begin 

return tpu$_success; 

end; 

[tpu$k_clo8e_delete]: lib$stop (..p_opcode); 
[otherwise]: lib$stop (..p_opcode); 
tea; 

return tpu$_success; 

END; ! End of routine TPU.IO 
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Example TPU-2 Normal VAXTPU Setup in VAX FORTRAN 


c 

c 

c 

c 


c 


c 


c 


c 

c 

c 


100 

c 


c 


c 


c 

c 


c 


c 


A sample FORTRAN program that calls VAXTPU to act 
normally, using the programmable interface. 


IMPLICIT NONE 


INTEGERS 
INTEGERS 
INTEGER*4 
INTEGER*4 


CLEAN.OPT 

STATUS 

BPV_PARSE(2) 

LOC.PARSE 


declare the VAXTPU functions 


!options for clean up routine 
!return status from VAXTPU routines 
!set up a Bound Procedure Value 
!a local function call 


INTEGERS 
INTEGER+4 
INTEGERS 
INTEGER*4 
INTEGER*4 


TPUICONTROL 

TPU$CLEANUP 

TPU$EXECUTE.INIFILE 

TPU$INITIALIZE 

TPU$CLIPARSE 


declare a local copy to hold the values of VAXTPU cleanup variables 

INTEGER*4 RESET.TERMINAL 

INTEGER*4 DELETE.JOURNAL 

INTEGER*4 DELETE.BUFFERS.DELETE.WINDOWS 

INTEGER*4 DELETE.EXITH,EXECUTE.PROC 

INTEGER*4 PRUNE.CACHE,KILL.PROCESSES 

INTEGER*4 CLOSE.SECTION 

declare the VAXTPU functions used as external 


EXTERNAL 

EXTERNAL 


TPU$HANDLER 

TPU$CLIPARSE 


EXTERNAL TPU$_SUCCESS {external error message 

EXTERNAL LOC.PARSE {user supplied routine to 

call TPUCLIPARSE and setup 

declare the VAXTPU cleanup variables as external these are the 
external literals that hold the value of the options 

EXTERNAL TPU$M_RESET_TERMINAL 

EXTERNAL TPU$M_DELETE_JOURNAL 

EXTERNAL TPU$M_DELETE_BUFFERS.TPU$M.DELETE_WINDOWS 

EXTERNAL TPU$M_DELETE_EXITH,TPU$M_EXECUTE_PROC 

EXTERNAL TPU$M_PRUNE_CACHE,TPU$M_KILL_PROCESSES 


CALL LIB$ESTABLISH ( TPU$HANDLER ) {establish the condition handler 

set up the Bound Procedure Value for the call to TPUlINITIALIZE 

BPV.PARSEC 1 ) = 7.L0C ( LOC.PARSE ) 

BPV_PARSE( 2 ) = 0 

call the VAXTPU initialization routine to do some set up work 
STATUS = TPUIINITIALIZE ( BPV.PARSE ) 


Check the status if it is not a success then signal the error 
IF ( STATUS .NE. y.L0C ( TPU$_SUCCESS ) ) THEN 

CALL LIB$SIGNAL( */.VAL( STATUS ) ) 

GOTO 9999 


END IF 

execute the TPU$_ init files and also a command file if it 
was specified in the command line call to VAXTPU 

STATUS = TPU$EXECUTE_INIFILE ( ) 

IF ( STATUS .NE. */.L0C ( TPU$_SUCCESS ) ) THEN {make sure everything is ok 

CALL LIB$SIGNAL( */.VAL( STATUS ) ) 

GOTO 9999 


END IF 

invoke the editor as it normally would appear 

STATUS = TPU$C0NTR0L ( ) {call the VAXTPU editor 

IF ( STATUS .NE. %L0C ( TPU$_SUCCESS ) ) THEN {make sure everything is ok 

CALL LIB$SIGNAL( */.VAL( STATUS ) ) 

GOTO 9999 


(Continued on next page) 
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Examples of Using VAXTPU Routines 


Example TPU-2 (Cont.) 


Normal VAXTPU Setup in VAX 
FORTRAN 


c 

c 

c 

c 



c 

c 


c 

c 

c 



9999 


C 

C 



C 


C 

C 


C 

9999 



END IF 

Get the value of the option from the external literals. In FORTRAN you 
cannot use external literals directly so you must first get the value 
of the literal from its external location. Here we are getting the 
values of the options that we want to use in the call to TPU$CLEANUP. 


DELETE.JOURNAL 

DELETE.EXITH 

DELETE.BUFFERS 

DELETE.WINDOWS 

EXECUTE.PROC 

RESET.TERMINAL 

KILL.PROCESSES 

CLOSE.SECTION 


= 7.L0C ( TPU$M_DELETE_JOURNAL ) 
= 7.L0C ( TPU$M_DELETE_EXITH ) 

= 7.L0C ( TPU$M_DELETE_BUFFERS ) 
= 7.L0C ( TPU$M_DELETE_WINDOWS ) 
= 7.L0C ( TPU$M_EXECUTE_PROC ) 

= 7.L0C ( TPU$M_RESET_TERMINAL ) 
= 7.L0C ( TPU$M_KILL_PROCESSES ) 
= 7.L0C ( TPU$M.CLOSE_SECTION ) 


Now that we have the local copies of the variables we can do the 
logical OR to set the multiple options that we need. 


CLEAN.OPT = DELETE.JOURNAL .OR. DELETE.EXITH .OR. 

1 DELETE.BUFFERS .OR. DELETE.WINDOWS .OR. EXECUTE.PROC 

1 .OR. RESET.TERMINAL .OR. KILL.PROCESSES .OR. CLOSE.SECTION 


do the necessary clean up 

TPU$CLEANUP wants the address of the flags as the parameter so 
pass the 7.L0C of CLEAN.OPT which is the address of the variable 

STATUS = TPU$CLEANUP ( 7.L0C ( CLEAN.OPT ) ) 

IF ( STATUS .NE. 7.L0C (TPUl.SUCCESS) ) THEN 
CALL LIB$SIGNAL( 7.VAL(STATUS) ) 


ENDIF 

CALL LIB$REVERT !go back to normal processing -- handlers 

STOP 

END 


INTEGERS FUNCTION LOC.PARSE 

INTEGER*4 BPV(2) !A local Bound Procedure Value 

CHARACTER*12 EDIT.COMM !A command line to send to TPU$CLIPARSE 

Declare the VAXTPU functions used 

INTEGER*4 TPU$FILEIO 

INTEGER*4 TPU$CLIPARSE 

Declare this routine as external because it is never called directly and 
we need to tell FORTRAN that it is a function and not a variable 

EXTERNAL TPU$FILEIO 

BPV(l) = 7.L0C(TPU$FILEI0) ! set up the BOUND PROCEDURE VALUE 

BPV(2) = 0 

EDIT_C0MM(1:12) = 'TPU TEST.TXT' 

parse the command line and build the item list for TPU$INITIALIZE 
LOC.PARSE = TPU$CLIPARSE (EDIT.COMM, BPV , 0) 

RETURN 

END 
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Example TPU-3 Building a Callback Item List with VAX 

FORTRAN 


PROGRAM TEST.TPU 

c 

IMPLICIT NONE 
C 

C Define the expected VAXTPU return statuses 

C 

EXTERNAL 
EXTERNAL 
C 

C Declare the 

C 

EXTERNAL 
EXTERNAL 
INTEGER*4 
INTEGERS 
INTEGER*4 
INTEGER*4 
INTEGER*4 
C 

C Declare the 

C 

EXTERNAL 
INTEGER*4 

INTEGER*4 
C 

C Declare the functions used for working with the condition handler 

C 

INTEGER*4 LIB$ESTABLISH 

INTEGER*4 LIB$REVERT 

C 

C Local Flags and Indices 

C 

INTEGER*4 CLEANUP.FLAG ! flag(s) for VAXTPU cleanup 

INTEGER*4 RET.STATUS 

C 

C Initializations 

C 

RET.STATUS = 0 

CLEANUP .FLAG = y.LOC (TPU$M_DELETE_CONTEXT) 

C 

C Establish the default VAXTPU condition handler 

C 

CALL LIB$ESTABLISH(*/.REF(TPU$HANDLER) ) 

C 

C Set up the bound procedure value for the initialization callback 

C 

BPV(l) = %LOC (TPU.STARTUP) 

BPV(2) * 0 

C 

C Call the VAXTPU procedure for initialization 

C 

RET.STATUS - TPU$INITIALIZE(BPV) 

IF (RET.STATUS .NE. %LOC(TPU$_SUCCESS)) THEN 
CALL LIBISIGNAL (%VAL(RET.STATUS)) 

ENDIF 

C 


TPU$_SUCCESS 

TPU$_QUITTING 

VAXTPU routines and symbols used 

TPU$M_DELETE_CONTEXT 

TPU$HANDLER 

TPU$M_DELETE_CONTEXT 

TPU$INITIALIZE 

TPU$EXECUTE_INIFILE 

TPUICONTROL 

TPU$CLEANUP 

external callback routine 

TPU.STARTUP ! the VAXTPU set-up function 

TPU.STARTUP 

BPV(2) ! Set up a bound procedure value 


(Continued on next page) 
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Examples of Using VAXTPU Routines 


Example TPU-3 (Cont.) Building a Callback Item List with VAX 

FORTRAN 


c 

c 


c 

c 

c 


c 

c 

c 


c 

c 

c 


c 

c 

c 


c 

c 

c 

c 

c 

c 


c 

c 

c 


Execute the VAXTPU initialization file 

RET.STATUS = TPU$EXECUTE_INIFILE() 

IF (RET.STATUS .NE. y.LOC(TPU$_SUCCESS)) THEN 
CALL LIB$SIGNAL (%VAL(RET.STATUS)) 

END IF 


Pass control to VAXTPU 


RET.STATUS = TPU$CONTROL() 

IF (RET.STATUS .NE. */.LOC(TPU$_QUITTING) 

1 .OR. y,LOC(TPU$_QUITTING)) THEN 

CALL LIB$SIGNAL OiVAL(RET.STATUS)) 

END IF 


Clean up after processing 

RET.STATUS = TPU$CLEANUP ('/.REF (CLEANUP.FLAG) ) 

IF (RET.STATUS .NE. %LOC(TPU$_SUCCESS)) THEN 
CALL LIB$SIGNAL (*/.VAL(RET.STATUS)) 

ENDIF 


Set the condition handler back to the default 


RET.STATUS = LIB$REVERT() 

END 

INTEGERS FUNCTION TPU.STARTUP 
IMPLICIT NONE 

INTEGER*4 OPTION.MASK ! temporary variable for VAXTPU 

CHARACTER*44 SECTION.NAME ! temporary variable for VAXTPU 


External VAXTPU routines and symbols 


EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

INTEGERS 


TPU$K_OPTIONS 

TPU$M.READ 

TPU$M_SECTION 

TPU$M_DISPLAY 

TPU$K_SECTIONFILE 

TPU$K_FILEIO 

TPU$FILEIO 

TPUIFILEIO 


The bound procedure value used for setting up the file I/O routine 
INTEGERS BPV (2) 


Define the structure of the item list defined for the callback 


STRUCTURE /CALLBACK/ 

INTEGER*2 BUFFER LENGTH 


INTEGER*2 
INTEGER*4 
INTEGER*4 
END STRUCTURE 


ITEM.CODE 
BUFFER.ADDRESS 
RETURN.ADDRESS 


There are a total of four items in the item list 
RECORD /CALLBACK/ CALLBACK (4) 


(Continued on next page) 
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Examples of Using VAXTPU Routines 


Example TPU-3 (Cont.) Building a Callback Item List with VAX 

FORTRAN 


c 

C Make sure it is not optimized! 

C 

VOLATILE /CALLBACK/ 

C 

C Define the options we want to use in the VAXTPU session 

C 

OPTION.MASK = %LOC(TPU$M_SECTION) .OR. y,LOC(TPU$M_READ) 

1 .OR. %L0C(TPU$M_DISPLAY) 

C 

C Define the name of the initialization section file 

C 

SECTION.NAME = 'device:[user]TPUSECTION.TPUlSECTION' 

C 

C Set up the required I/O routine. Use the VAXTPU default. 

C 

BPV(l) = '/.LOC (TPU$FILEIO) 

BPV(2) = 0 
C 

C Build the callback item list 

C 

C Set up the edit session options 

C 

CALLBACK(1).ITEM.CODE = %LOC(TPU$K_OPTIONS) 

CALLBACK(l).BUFFER.ADDRESS = KLOC(OPTION.MASK) 

CALLBACK(1).BUFFER.LENGTH * 

CALLBACK(1).RETURN.ADDRESS = 0 
C 

C Identify the section file to be used 

C 

CALLBACKS) .ITEM.CODE = %LOC(TPU$K_SECTIONFILE) 

CALLBACK(2).BUFFER.ADDRESS = %L0C(SECTION.NAME) 

CALLBACK(2).BUFFER.LENGTH = LEN(SECTION.NAME) 

CALLBACK(2).RETURN.ADDRESS = 0 
C 

C Set up the I/O handler 

C 

CALLBACK(3).ITEM.CODE * %LOC(TPU$K.FILEIO) 

CALLBACK(3).BUFFER.ADDRESS = %L0C(BPV) 

CALLBACK(3).BUFFER.LENGTH = 4 
CALLBACK(3).RETURN.ADDRESS = 0 
C 

C End the item list with zeros to indicate we are finished 

C 

CALLBACK(4).ITEM.CODE = 0 
CALLBACK(4).BUFFER.ADDRESS = 0 
CALLBACK(4).BUFFER.LENGTH = 0 
CALLBACK(4).RETURN.ADDRESS = 0 
C 

C Return the address of the item list 

C 

TPU.STARTUP = y.LOC (CALLBACK) 

RETURN 

END 
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Examples of Using VAXTPU Routines 


Example TPU-4 


Specifying a User-Written File I/O Routine in 
VAX C 





/* 

Simple example of a C program 
own FILEIO routine instead of 
*/ 

♦include descrip 
♦include stdio 

/* data structures needed */ 


to invoke TPU. This program provides its 
using the one provided by TPU. 


struct bpv_arg 

/* 

bound procedure value */ 

int *routine_add ; 

/* 

pointer to routine */ 

int env ; 

> ; 

/* 

environment pointer */ 

struct item_list_entry 

X 

/* 

item list data structure */ 

\ 

short int buffer_length; 

/* 

buffer length */ 

short int item.code; 

/* 

item code */ 

int *buffer_add; 

/* 

buffer address */ 

int *retura_len_add; 

/* 

return address */ 


struct 8tream_type 

{ 

int ident; 
short int alloc; 
short int flags; 
short int length; 
short int stuff; 
int nam_add; 

> ; 

globalvalue tpu$_success; 
globalvalue tpu$_quitting; 

globalvalue 


/* stream id */ 

/* file size */ 

/* file record attributes/format */ 

/* resultant file name length */ 

/* file name descriptor class & type */ 

/* file name descriptor text pointer */ 


/* TPU Success code */ 

/* Exit code defined by TPU */ 

/* Cleanup codes defined by TPU */ 
tpu$m_delete_journal, tpu$m_delete_exith, 

tpu$m_delete_buffers, tpu$m_delete_windows, tpu$m_delete_cache, 
tpu$m_prune_cache, tpu$m_execute_file, tpu$m_execute_proc, 
tpu$m_delete_context, tpu$m_reset.terminal, tpu$m_kill_processes, 
tpu$m_clo8e_section, tpu$m_delete_others, tpu$m_last_time; 

globalvalue /* Item codes for item list entries */ 

tpu$k_fileio, tpu$k_options, tpu$k_sectionfile, 
tpu$k_commandfile ; 

globalvalue /* Option codes for option item */ 

tpu$m_display, tpu$m_section, tpu$m_command, tpu$m_create ; 

globalvalue /* Possible item codes in item list */ 

tpu$k_acce88, tpu$k_filename, tpu$k_defaultfile, 
tpu$k_relatedfile, tpu$k_record_attr, tpu$k_maximize_ver, 
tpu$k_flush, tpu$k_file8ize; 


(Continued on next page) 
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Examples of Using VAXTPU Routines 


Example TPU—4 (Cont.) Specifying a User-Written File I/O 

Routine in VAX C 


globalvalue 

tpu$k_io, tpu$k_input, 


/* Possible access types tor tpu$k_access */ 
tpu$k_output; 


globalvalue 
rms$_fnf; 
globalvalue 

tpu$k_open, tpu$k_close, 
tpu$k_get, tpu$k_put; 
int lib$establish (); 
int tpu$cleanup (); 
int tpu$control (); 
int tpu$execute_inifile (); 
int tpu$handler (); 
int tpu$initialize (); 


/* RMS File Not Found message code */ 

/* FILEIO routine functions */ 
tpu$k_clo8e_delete. 

/* RTL routine to establish an event handler */ 
/* TPU routine to free resources used */ 

/* TPU routine to invoke the editor */ 

/* TPU routine to execute initialization code */ 
/* TPU signal handling routine */ 

/* TPU routine to initialize the editor */ 


/* 

This function opens a file for either read or write access, based upon 
the itemlist passed as the data parameter. Note that a full implementation 
of the file open routine would have to handle the default file, related 
file, record attribute, maximize version, flush and file size item code 
properly. 

*/ 

open.file (data, stream) 


int *data; 

struct stream.type *stream; 

struct item_list_entry *item; 

char *access; /* File access type */ 

char filename [256]; /* Max file specification size */ 

FILE *f openQ ; 

/* Process the item list */ 
item = data; 

while (item->item_code != 0 && item->buffer_length != 0) 

if (item->item_code == tpu$k_access) 

if (item->buffer_add == tpu$k_io) access = M r+ M ; 
else if (item->buffer_add == tpu$k_input) access = "r"; 
else if (item->buffer_add == tpu$k_output) access * "w"; 
> 


(Continued on next page) 
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Example TPU-4 (Cont.) Specifying a User-Written File I/O 

Routine in VAX C 


> 

/* 


else if (item->item_code == tpu$k_filename) 

i 


8trncpy (filename, item->buffer_add, item->buffer.length); 
filename [item->buffer_length] = 0; 

lib$scopy_r_dx (&item->buffer_length, item->buffer_add, 

&stream->length); 


> 

else if 

> 

else if 

> 

else if 

> 

else if 

> 

else if 

< 

> 

else if 

> 

++item; 

> 


(item->item_code == 

(item->item_code == 

(item->item_code == 

(item->item_code == 

(item->item_code == 

(item->item_code == 
/* get next 


tpu$k_defaultfile) 

/* Add code to handle default file */ 


/* spec here */ 

tpu$k_relatedfile) 

/* Add code to handle related */ 

/* file spec here */ 

tpu$k_record_attr) 

/* Add code to handle record */ 

/* attributes for creating files */ 

tpu$k_maximize_ver) 

/* Add code to maximize version */ 

/* number with existing file here */ 

tpu$k_flush) 

/* Add code to cause each record */ 


/* to be flushed to disk as written */ 
tpu$k_filesize) 

/* Add code to handle specification */ 
/* of initial file allocation here */ 
item */ 


stream->ident = fopen(filename,access); 
if (stream->ident != 0) 
return tpu$_success; 

else 


return rms$_fnf; 


This procedure closes a file 
*/ 

close.file (data.stream) 
struct stream.type *stream; 


clo8e(8tream->ident); 
return tpu$_success; 

> 

/* 

This procedure reads a line from a file 
*/ 

read_line(data,stream) 
struct dscldescriptor *data; 
struct stream_type *stream; 

< 

char textline[984]; /* max line size for TPU records */ 

int len; 

globalvalue rms$_eof; /* RMS End-Of-File code */ 

if (fgets(textline,984,stream->ident) == NULL) 
return rms$_eof; 

else 

len = strlen(textline); 
if (len > 0) 

len - len - 1; 

return lib$scopy_r_dx (Alen, textline, data); 

> 

> 


(Continued on next page) 
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Examples of Using VAXTPU Routines 


Example TPU-4 (Cont.) Specifying a User-Written File I/O 

Routine in VAX C 


/* 

This procedure writes a line to a tile 
*/ 

write_line(data.stream) 
struct dsc$descriptor ♦data; 
struct stream_type *stream; 

char textline[984]; /♦ max line size lor TPU records */ 

strncpy (textline, data->dsc$a_pointer, data->dsc$w_length); 

textline [data->dsc$w_length] = 0; 

fputs(textline,stream->ident); 

fputs("\n",stream->ident); 

return tpu$_success; 

> 

/* 

This procedure will handle I/O for TPU 

*/ 

fileio(code,stream,data) 
int ♦code; 
int ♦stream; 
int ♦data; 


int status; 


/♦ Dispatch based on code type. Note that a full implementation of the ♦/ 
/♦ file I/O routines would have to handle the close and delete code properly ♦/ 
/♦ instead of simply closing the file ♦/ 


if (*code == tpu$k_open) 

status = open.file (data,stream); 
else if (♦code == tpu$k_close) 

status = close_file (data,stream); 
else if (♦code == tpu$k_close_delete) 
status = close_file (data,stream); 
else if (*code == tpu$k_get) 

status = read.line (data,stream); 
else if (*code == tpu$k_put) 

status = write.line (data,stream); 


/♦ Initial access to file ♦/ 

/♦ End access to file ♦/ 

/♦ Treat same as close ♦/ 

/♦ Read a record from a file ♦/ 
/* Write a record to a file ♦/ 


else 

{ /♦ Who knows what we got? ♦/ 

status = tpu$_success; 

printf ("Bad FILEI0 I/O function requested"); 

> 


return status; 

> 


(Continued on next page) 
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Example TPU-4 (Cont.) Specifying a User-Written File I/O 

Routine in VAX C 


/* 

This procedure formats the initialization item list and returns it as 
is return value. 

*/ 

callrout() 

< 

static struct bpv.arg add_block = 

{ fileio, 0 > ; /* BPV for fileio routine */ 

int options ; 

char *section_name = "TPUSECINI"; 
static struct item.list.entry arg[] = 

{/* length code buffer add return add */ 


i 4,tpu$k_fileio. 

0. 

0 >. 

{ 4,tpu$k.options, 

0, 

0 >. 

{ 0,tpu$k_sectionfile,0, 

0 >. 

*C 0.0, 

0 . 

0 > 


>; 

/* Setup file I/O routine item entry */ 
arg[0].buffer.add = fcadd.block; 

/* Setup options item entry. Leave journaling off. */ 
options * tpu$m_display I tpu$m_section; 
arg[l].buffer_add * ^options; 

/* Setup section file name */ 

arg[2].buffer.length * strlen(section_name); 

arg[2].buffer_add = section.name; 

return arg; 

> 

/* 

Main program. Initializes TPU, then passes control to it. 

*/ 

mainO 

int return.status ; 
int cleanup.options; 
struct bpv.arg add.block; 

/* Establish as condition handler the normal VAXTPU handler */ 
lib$establish(tpu$handler); 

/* Setup a BPV to point to the callback routine */ 
add_block.routine_add = callrout ; 
add.block.env * 0; 

/* Do the initialize of VAXTPU */ 

return.status = tpu$initialize(&add_block); 
if (!return_status) 

exit(return.status); 

/* Have TPU execute the procedure TPU$INIT_PROCEDURE from the section file */ 
/* and then compile and execute the code from the command file */ 
return.status = tpu$execute_inifile(); 
if (!return.status) 

exit (return.status); 


(Continued on next page) 
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Example TPU-4 (Cont.) Specifying a User-Written File I/O 

Routine in VAX C 


/* Turn control over to VAXTPU */ 
return.status = tpu$control (); 
i1 (!return_status) 

exit(return_status); 

/* Now clean up. */ 

cleanup_option8 * tpu$m_last_time I tpu$m_delete_context; 
return.status * tpu$cleanup (fccleanup.options); 
exit (return.status); 
printi("Experiment complete"); 


12.5 VAXTPU Routines 

The following pages describe the individual VAXTPU routines in routine 
template format. 
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TPU$CLEANUP 

Cleans up internal data structures, free memory, and restores 
terminals to their initial state. This is the last routine that you call. 

FORMAT 

TPUSCLEANUP flags 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Longword bit mask. The flags argument is the address of a longword bit 
mask defining the cleanup options. The address of a 32-bit mask defining the 
cleanup options. This mask is the logical OR of the flag bits that you wish to 
set. TPU$V... indicates a bit item and TPU$M... indicates a mask. Following 
are the various cleanup options: 


Symbol 1 

TPU$M_DELETE_JOURNAL 

TPU$M_DELETE_EXITH 

TPU$M_DELETE_BUFFERS 


TPU$M _DELETE—WINDOWS 


Function 

Closes and deletes the journal file if it is open. 
Deletes VAXTPU's exit handler. 

Delete all text buffers. If this is not the last 
time you are calling VAXTPU, then all variables 
referring to these data structures are reset, as 
in the built-in procedure DELETE. If a buffer is 
deleted, then all ranges and markers within that 
buffer, and any subprocesses using that buffer, 
are also deleted. 

Deletes all windows. If this is not the last 
time you are calling VAXTPU, then all variables 
referring to these data structures are reset, as in 
the built-in procedure DELETE. 


Prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask in which the bit is 
set corresponds to the specific field; TPU$V_ is a bit number. 
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TPU$CLEANUP 


Symbol 1 

Function 

TPU$M_DELETE_CACHE 

Deletes the virtual file manager's data structures 
and caches. If this deletion is requested, then all 
buffers are also deleted. If the cache is deleted, 
the initialization routine has to reinitialize the 
virtual file manager the next time it is called. 

TPU$M_PRUNE_CACHE 

Frees up any virtual file manager caches that 
have no pages allocated to buffers. This frees 
up any caches that may have been created 
during the session but are no longer necessary. 

TPU$M .EXECUTE -FILE 

Reexecutes the command file if 
TPU$EXECUTE_INIFILE is called again. You 
must set this bit if you plan on specifying a new 
file name for the command file. This option is 
used in conjunction with the option bit passed 
to TPUSlNITIALIZE indicating the presence of 
the /COMMAND qualifier. 

TPU$M -EXECUTE _PROC 

Looks up TPU$INIT_PROCEDURE and executes 
it the next time TPU$EXECUTE_INIFILE is 
called. 

TPUSM _DELETE_CONTEXT 

Deletes the entire context of VAXTPU. If this 
option is specified, then all other options are 
implied, except for executing the initialization file 
and initialization procedure. 

TPUSM _RESET_TERMINAL 

Resets the terminal to the state it was in 
upon entry to VAXTPU. The terminal mailbox 
and all windows are deleted. If the terminal 
is reset, then it is reinitialized the next time 
TPUSlNITIALIZE is called. 

TPUSM -KILL -PROCESSES 

Deletes all subprocesses created during the 
session. 

TPUSM—CLOSE—SECTION 2 

Closes the section file and releases the 
associated memory. All buffers, windows 
and processes are deleted. The cache is pruned 
and the flags for re-execution of the initialization 
file and initialization procedure are set. If the 
section is closed, and if the option bit indicates 
the presence of the SECTION qualifier, then the 
next call to TPUSlNITIALIZE attempts a new 
restore operation. 

TPUSM—DELETE—OTHERS 

Deletes all miscellaneous preallocated data 
structures. Memory for these data structures 
is reallocated the next time TPUSlNITIALIZE is 
called. 


Prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask in which the bit is 
set corresponds to the specific field; TPU$V_ is a bit number. 

2 Using the simplified callable interface does not set TPU$_CLOSE_SECTION. This 
feature allows you to make multiple calls to TPUSTPU without requiring you to 
open and close the section file on each call. 
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Symbol 1 

Function 

TPU$M _LAST_TIME 

This bit should be set only when you are calling 
VAXTPU for the last time. Note that if you set 
this bit and then recall VAXTPU, the results are 
unpredictable. 

Prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask in which the bit is 
set corresponds to the specific field; TPU$V_ is a bit number. 


The following bits in the mask can also be set. 

• TPU$V_DELETE-JOURNAL 

• TPU$V_DELETE _EXITH 

• TPU$ V—DELETE —BUFFERS 

• TPU$ V—DELETE —WINDOW S 

• TPU$V_DELETE—CACHE 

• TPU$V_PRUNE-CACHE 

• TPU$V_EXECUTE—FILE 

• TPU$V_EXECUTE—PROC 

• TPU$V_DELETE-CONTEXT 

• TPU$V_RESET—TERMINAL 

• TPU$V_KILL -PROCESSES 

• TPU$V_CLOSE—SECTION 

• TPU$V_DELETE—OTHERS 

• TPU$V_LAST—TIME 


DESCRIPTION The cleanup routine is the final routine called in each interaction with 

VAXTPU. It tells VAXTPU to clean up its internal data structures and prepare 
for additional invocations. You can control what is reset by this routine by 
setting or clearing the flags described above. 

When you finish with VAXTPU, call this routine to free the memory and 
restore the characteristics of the terminal to their original settings. 

If you intend to exit after calling TPU$CLEANUP, do not delete the data 
structures; this is done automatically by the system. Allowing the VAX/VMS 
system to delete the structures improves the performance of your program. 

Notes 

1 When you use the simplified interface, VAXTPU automatically sets the 
following flags: 

• TPU$V_RESET_TERMINAL 

• TPU$ V_DELETE —BUFFERS 

• TPU$ V-DELETE -JOURNAL 
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• TPU$V_DELETE_WINDOWS 

• TPU$ V—DELETE _EXITH 

• TPU$ V—EXECUTE _PROC 

• TPU$ V—EXECUTE —FILE 

• TPU$V_PRUNE—CACHE 

• TPU$V_KILL-PROCESSES 

2 If this routine does not return a success status, no other calls to the editor 
should be made. 
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TPU$CLIPARSE 



Parses a command line and build the item list for TPU$INITIALIZE. 

It calls CLI$DCI_PARSE to establish a command table and a 

command to parse. It then calls TPU$PARSEINFO to build an item 
list for TPUSINITIALIZE. 

FORMAT 

TPU$CLIPARSE string, fileio, calluser 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Command line. The string argument is the address of a descriptor of a 
VAXTPU command. 

fileio 

VMS Usage: vector_longword_unsigned 
type: bound procedure value 

access: read only 

mechanism: by descriptor 

File I/O routine. The fileio argument is the address of a descriptor of a file 
I/O routine. 

calluser 

VMS Usage: vector_longword_unsigned 
type: bound procedure value 

access: read only 

mechanism: by descriptor 

Calluser routine. The calluser argument is the address of a descriptor of a 
calluser routine. 
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TPU$CONTROL 



Is the main processing routine of the VAXTPU editor. When you 
call this routine (after calling TPU$INITIALIZE), control is turned over 
to VAXTPU. 

FORMAT 

TPU$CONTROL 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

None. 

DESCRIPTION 

This routine controls the edit session. It is responsible for reading the text 
and commands and executing them. Windows on the screen are updated to 
reflect the edits that are performed. 


Note: Control is returned to your program only if an error occurs or after you 



issue either the built-in procedure QUIT or the built-in procedure EXIT. 

CONDITION 

VALUES 

RETURNED 

TPU$_EXITING Returning as a result of EXIT (when the default 

condition handler is established). 

TPU$_QUITTING Returning as a result of QUIT (when the default 

condition handler is established). 

TPU$_RECOVERFAIL Returning because a recovery operation was 

abnormally terminated. 
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TPU$EDIT 



Is another entry point to VAXTPU's simplified callable interface. 
TPU$EDIT builds a command string from its parameters and passes 
it to the TPU$TPU routine. 

FORMAT 

TPU$EDIT input, output 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

input 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Input file passed by descriptor. The input argument is the address of a 
descriptor of a file specification. 

output 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Character string to be used with the /OUTPUT command qualifier. The 
output argument is the address of a descriptor of an output file specification. 

DESCRIPTION 

This routine builds a command string and passes it to TPU$TPU. If the length 
of the output string is greater than 0, it is included in the command line using 
the /OUTPUT qualifier as follows: 

TPU [/0UTPUT= output] input 

CONDITION 

VALUES 

RETURNED 

Any value returned by TPU$TPU 
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TPU$EXECUTE_COMMAND 



Gives your program access to the execution of VAXTPU 
commands. 

FORMAT 

TPU$EXECUTE_COMMAND string 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by value 

Character string. The string argument is the address of a descriptor of a 
character string denoting a VAXTPU command. 


DESCRIPTION This routine performs the same function as the built-in procedure EXECUTE 

procedure described in the VAX Text Processing Utility Reference Manual. 


CONDITION 

VALUES 

RETURNED 

TPU$_SUCCESS Normal successful completion. 

TPU$_EXITING EXIT built-in procedure was invoked. 

TPU$_QUITTING QUIT built-in procedure was invoked. 

TPU$_EXECUTEFAIL Execution aborted. This could be because of 

execution errors or compilation errors. 
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TPU$EXECUTE_INIFILE 



Allows you to execute a user-written initialization file. If you intend 
to use this routine, it must be executed after initializing the editor, 
and before processing any other commands. 

FORMAT 

TPU$EXECUTE_INIFILE 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

None. 

DESCRIPTION 

This routine first checks to see if a section file has been mapped in 
successfully. If so, it looks up the symbol TPU$INIT__PROCEDURE, and 
if this symbol is a procedure it executes it. Next, the routine checks to see if 
the /COMMAND qualifier is specified. If so, it creates a buffer and reads the 
file into it. This buffer is then compiled and executed. 


Note: If you call this routine after calling TPU$CLEANUP, you must set 



the flags TPU$_EXECUTEPROCEDURE and TPU$_EXECUTEFILE. 
Otherwise, the initialization file does not execute. 

CONDITION 

VALUES 

RETURNED 

TPU$_SUCCESS Normal successful completion. 

TPU$_EXITING Returning as a result of EXIT. If the default 

condition handler is being used, the session is 
terminated. 

TPU$_QUITTING Returning as a result of QUIT. If the default 

condition handler is being used, the session is 
terminated. 

TPU$_COMPILEFAIL The compilation of the initialization file was 

unsuccessful. 

TPU$_EXECUTEFAIL The execution of the statements in the initialization 

file was unsuccessful. 

TPU$_FAILURE General code for all other errors. 
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TPU$FILEIO 



Handles file operations. Your own file I/O routine can call this 
routine to perform some operations for it. However, the routine 
that opens the file must perform ALL operations for that file. For 
example, if TPU$FILEIO opens the file, it must also close it. 

This routine always puts values greater than 511 in the first 
longword. Because a user-written file I/O routine is restricted to 
the values 0-511, you can easily distinguish the file control blocks 
(FCB) this routine fills in from the ones you created. 

FORMAT 

TPU$FILEIO code , stream, data 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

The file I/O routine returns an RMS status code to VAXTPU. The file I/O 
routine is responsible for signaling all errors if any messages are desired. 

ARGUMENTS 

code 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item code. The code argument is the address of a longword that contains an 
item code from VAXTPU which specifies a function to perform. 

Following are the item codes that can be specified in the file I/O routine: 

• TPU$K_OPEN—This item code specifies that the data parameter is the 
address of an item list. This item list contains the information necessary 
to open the file. The stream parameter should be filled in with a unique 
identifying value to be used for all future references to this file. The 
resultant file name should also be copied with a dynamic string descriptor. 

• TPU$K_CLOSE—The file specified by stream is to be closed. All memory 
being used by its structures can be released. 

• TPU$K_CLOSE—DELETE—The file specified by stream is to be closed 
and deleted. All memory being used by its structures can be released. 

• TPU$K_GET—The data parameter is the address of a dynamic string 
descriptor to be filled with the next record from the file specified by 
stream. The routine should use the routines provided by the VAX/VMS 
Run-Time Library to copy text into this descriptor. VAXTPU will free the 
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memory allocated for the data read when the file I/O routine indicates the 
end of the file has been reached. 

• TPU$K_PUT—The data parameter is the address of a descriptor for the 
data to be written to the file specified by stream. 


stream 


VMS Usage: 
type: 
access: 
mechanism: 


unspecified 
longword (unsigned) 
modify 
by reference 


File description. The stream argument is the address of a data structure 
consisting of four longwords. This data structure is used to describe the file to 
be manipulated. 

This data structure is used to refer to all files. It is written to when an open 
file request is made. All other requests use information in this structure to 
determine which file is being referenced. 

The structure consists of a block of 4 longwords. Figure TPU-2 shows the 
stream data structure. 

Figure TPU-2 Stream Data Structure 


FILE IDENTIFIER 

RFM 

RAT 

ALLOCATION 

CLASS 

TYPE 

LENGTH 

ADDRESS OF NAME 
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The first longword is used to hold a unique identifier for each file. The user- 
written file I/O routine is restricted to values between 0 and 511. Thus, you 
can have up to 512 files open simultaneously. 

The second longword is divided into 3 fields. The low word is used to store 
the allocation quantity from the FAB (FAB$L_ALQ), that is, the number of 
blocks allocated to this file. This value is later used to calculate the output file 
size for preallocation of disk space. The low order byte of the second word is 
used to store the record attribute byte (FAB$B_RAT) when an existing file is 
opened. The high byte is used to store the record format byte (FAB$B_RFM) 
when an existing file is opened. These are used for creating the output file 
in the same format as the input file. These fields are to be filled in by the 
routine opening the file. 

The last two longwords are used as a descriptor for the resultant or the 
expanded file name. This name is used later when processing EXITs. This 
descriptor is to be filled in with the file name after an open operation. It 
should be allocated with either the routine LIB$SCOPY_R_DX or the routine 
LIB$SCOPY_DX from the run-time library. This space is freed by VAXTPU 
when it is no longer needed. 
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data 

VMS Usage: 
type: 
access: 
mechanism: 


item_list_3 
longword (unsigned) 
modify 
by reference 


Stream data. The data argument is either the address of an item list 


Note: The data is the address of a descriptor depending on the item code you 
choose. 


The meaning of this parameter depends on the item code specified in the 
code field. 

When the TPU$K_OPEN item code is issued, the data parameter is the 
address of an item list containing information about the open request. The 
following VAXTPU item codes are available for specifying information about 
the open request. 

• TPU$K_ACCESS—This item code allows you to specify one of the 
following item codes in the buffer address field. These three set indicators 
in the RMS file access block (FAB) indicate the type of access desired: 

TPU$K_IO—OFP = TRUE (output file parse) 

TPU$K_INPUT—PUT = FALSE (no write access to file) 
TPU$K_OUTPUT—OFP = TRUE (output file parse), GET = FALSE (no 
read access to a file) 

If you need further information on these indicators see the VAX Record 
Management Services Reference Manual . 

• TPU$K_FILENAME—This item code is used for specifying the address 
of a string to use as the name of the file you are opening. The length 
field contains the length of this string and the address field contains the 
address. 

• TPU$K_DEFAULTFILE—This item code is used for assigning a default 
file name to the file being opened. The buffer length field contains the 
length and the buffer address field contains the address of the default file 
name. 

• TPU$K_RELATEDFILE—This item code is used for specifying a related 
file name for the file being opened. The buffer length field contains the 
length and the buffer address field contains the address of a string to use 
as the related file name. 

• TPU$K_RECORD_ATTR—This item code specifies that the buffer address 
field contains the value for the record attribute byte in the FAB 
(FAB$B_RAT) used for file creation. 

• TPU$K_RECORD_FORM—This item code specifies that the buffer 
address field contains the value for the record format byte in the FAB 
(FAB$B_RFM) used for file creation. 

• TPU$K_MAXIMIZE_VER—This item code specifies that the version 
number of the output file should be maximized with those that currently 
exist. 

• TPU$K_FLUSH—This item code specifies that the file should have every 
record flushed after it is written. 
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• TPU$K_FILESIZE—This item code is used for specifying a value to 
be used as the allocation quantity when creating the file. The value is 
specified in the buffer address field. 


DESCRIPTION By default, TPU$FILEIO creates variable length files with carriage return 
record attributes (fab$b_rfm = var, fab$b_rat = cr). If you pass it the 
TPU$K_RECORD_ATTR or TPU$K_RECORD_FORM items, they are used 
instead. The following combinations of formats and attributes are acceptable: 


FORMAT ATTRIBUTES 

STM,STMLF,STMCR 0,BLK,CR,BLK+CR 

VAR 0,BLK,FTN^R,BLK4FTN,BLK+C^ 

All other combinations are converted to VAR format with CR attributes. 

Note: VAXTPU uses TPU$FILEIO by default when you use the simplified 
callable interface. When you use the full callable interface, you must 
explicitly invoke TPU$FILEIO or provide your own file I/O routine. 
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TPU$HANDLER 

Is VAXTPU's condition handler. The VAXTPU condition handler 
invokes the Put Message (SYS$PUTMSG) system service, passing it 
the address of TPU$MESSAGE. 


FORMAT TPUSHANDLER signal _ vector , mechanism— vector 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 


"CONDITION VALUES RETURNED." 


ARGUMENTS 


signal—vector 


VMS Usage: 
type: 
access: 
mechanism: 


arg_list 

longword (unsigned) 

modify 

by reference 


Signal vector. See the VAX/VMS System Services Reference Manual for 
information about the signal vector passed to a condition handler. 


mechanism—vector 


VMS Usage: 
type: 
access: 
mechanism: 


arg_list 

longword (unsigned) 
read only 
by reference 


See the VAX/VMS System Services Reference Manual for information about the 
mechanism vector passed to a condition handler. 


DESCRIPTION The TPU$MESSAGE routine does the actual output of the message. The 

Put Message (SYS$PUTMSG) system service only formats the message. It 
gets the settings for the message flags and facility name from the variables 
described in Section 12.1.2. Those values can only be modified by the 
VAXTPU built-in procedure SET. 

If the condition value received by the handler has a FATAL status, or does 
not have VAXTPU's facility code, the condition is resignaled. 

If the condition is TPU$_QUITTING, TPU$_EXITING or 
TPU$__RECOVERFAIL, a request to UNWIND is made to the establisher of 
the condition handler. 
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After handling the message, the condition handler returns with a continue 
status. VAXTPU error message requests are made by signaling a condition 
to indicate which message should be written out. The arguments in the 
signal array are a correctly formatted message argument vector. This vector 
sometimes contains multiple conditions and formatted ASCII output (FAO) 
arguments for the associated messages. For example, if the editor attempts to 
open a file that does not exist, the VAXTPU message TPU$_NOFILEACCESS 
is signaled. The FAO argument to this message is a string for the name of 
the file. This condition has an error status, followed by the VAX RMS fields 
STS and STV. Because this condition does not have a fatal severity, the editor 
continues after handling the error. 

The editor does not automatically return from TPU$CONTROL. If you call 
the TPU$CONTROL routine, you must explicitly establish a way to regain 
control (for example, using the built-in procedure CALL—USER). Also, if 
you establish your own condition handler, but call the VAXTPU handler for 
certain conditions, the default condition handler must be established at the 
point in your program where you want to return control. 

See the Introduction to VAX/VMS System Routines for information about the 
VAX Condition Handling Standard. 
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TPU$INITIALIZE 


Initializes VAXTPU for editing. This routine allocates global data 
structures, initializes global variables, and calls the appropriate set¬ 
up routines for each of the major components of the editor, including 
the Virtual File Manager, Screen Manager, and I/O subsystem. 

FORMAT 

TPUSINITIALIZE callback 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


Longword condition value. All utility routines return a condition value in 

R0. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 


ARGUMENT 


callback 

VMS Usage: 
type: 
access: 
mechanism: 


vector_longword_unsigned 
bound procedure value 
read only 
by descriptor 


Callback routine. The callback argument is the address of a routine that 
returns the address of an item list containing initialization parameters or a 
routine for handling file I/O operations. 

The DCL interface routine provided by VAXTPU TPU$CLI_PARSE can be 
used as the callback routine. Callable VAXTPU defines nine item codes that 
can be used for specifying intialization parameters. You don't have to arrange 
the item codes in any particular order in the list. Figure TPU-3 shows the 
general format of an item descriptor. For information about how to build an 
item list, refer to the VAX/VMS programmer's manual associated with the 
language you are using. 


Figure TPU-3 Format of an Item Descriptor 
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The return address in an item descriptor is usually 0. 
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The following item codes are available to you: 


Item code 

Description 

TPU$K_OPTIONS 

Enables the command qualifiers. Seven bits in the 
buffer address field correspond to the various TPU 
command qualifiers. The remaining 25 bits in the 
buffer address field are reserved. 

TPU$K_JOURNALFILE 

Passes the string specified with the /JOURNAL 
qualifier. The buffer length field is the length of the 
string and the buffer address field is the address of 
the string. This is the string that is available with 
GET_INFO (COMMAND—LINE, "JOURNAL—FILE"). This 
string may be a null string. 

TPU$K_SECTIONFILE 

Passes the string that is the name of the binary 
initialization file (section file) to be mapped in. The 
buffer length field is the length of the string and the 
buffer address field is the address of the string. The 
VAXTPU CLD file has a default value for this string. 
This item code must be specified if the 
TPU$V_SECTION bit is set. 

TPU$K_OUTPUTFILE 

Passes the string specified with the /OUTPUT 
qualifier. The buffer length field is the length of 
the string and the buffer address field specifies 
the address of the string. This is the string that 
is returned by the built-in procedure GET_INFO 
(COMMAND_LINE, "OUTPUT_FILE"). The string may 
be a null string. 

TPU$K_DISPLAYFILE 

Passes the string specified with the /DISPLAY 
qualifier. The buffer length field is the length of 
the string and the buffer address field specifies the 
address of the string. 

TPU$K_COMMANDFILE 

Passes the string specified with the /COMMAND 
qualifier. The buffer length field is the length 
of the string and the buffer address field is the 
address of the string. This string is returned by 
the built-in procedure GET_INFO (COMMAND—LINE, 
"COMMAND_FILE"). The string may be a null string. 

TPU$K_FILENAME 

Passes the string that is the name of the input file 
specified in the command line. The buffer length 
field specifies the length of this string and the buffer 
address field specifies its address. This is the string 
that is returned by the built-in procedure GET—INFO 
(COMMAND—LINE, "FILE—NAME"). This file name 
may be a null string. 

TPU$K_FILEIO 

Passes the bound procedure value of a routine to be 
used for handling file operations. You may provide 
your own file I/O routine or you can call TPU$FILEIO, 
the utility routine provided by VAXTPU for handling 
file operations. The address of the file I/O routine is 
specified in the buffer address field. 
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Item code 

Description 

TPU$K_C ALLUSER 

Passes the bound procedure value of the user-written 
routine that the built-in procedure CALL_USER is to 
call. The address of this routine is specified in the 
buffer address field. 


Mask 

Flag 

Function 

TPUSM—RECOVER 1 

TPU$V_RECOVER 2 

Performs a recovery operation. 

TPU$M_JOURNAL 

TPU$V_JOURNAL 

Journals the edit session. 

TPU$M_READ 

TPU$V_READ 

Makes this a READ-ONLY edit 
session for the main buffer. 

TPU$M_SECTION 

TPU$V_SECTION 

Maps in a binary initialization file 
(a VAXTPU section file) during 
startup. 

TPU$M_CREATE 

TPUSV—CREATE 

Creates an input file if the one 
specified does not exist. 

TPU$M_OUTPUT 

TPU$V_OUTPUT 

Writes the modified input file 
upon exiting. 

TPU$M_COMMAND 

TPU$V_COMMAND 

Executes a command file during 
startup. 

TPU$M_DISPLAY 

TPU$V_DISPLAY 

Attempts to use the terminal 
for screen-oriented editing and 
display purposes. 

^PUSM... indicates a mask. 

2 TPU$V... indicates a bit item. 


To create the flags, start with the value 0, then use the OR operator on 
the mask (TPU$M...) of each item you want to set. Another way to create 
the flags is to treat the 32 bits as a bitvector and set the bit (TPU$V...) 
corresponding to the item you want. 

Note: If this routine does not return a success status, no other calls to the editor 
should be made. 


DESCRIPTION This is the first routine that must be called after establishing a condition 

handler. 

This routine initializes the editor according to the information received from 
the callback routine. The initialization routine defaults all file specifications to 
the null string and all options to off. However, it does not default the file I/O 
or calluser routine addresses. 

If you do not specify a section file, the software features of the editor are 
limited. 
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TPUSINITIALIZE 


CONDITION 

TPU$_SUCCESS 

Initialization was successfully completed. 

VALUES 

TPU$_SYSERROR 

A system service did not work correctly. 

RETURNED 

TPU$_NONANSICRT 

The input device (SYS$INPUT) is not a supported 
terminal. 


TPUS—RESTOREFAIL 

An error occurred during the restore operation. 


TPU$_NOFILEROUTINE 

No routine has been established to perform file 
operations. 


TPU$_INSVIRMEM 

Insufficient virtual memory exists for the editor to 
initialize. 


TPU$_FAILURE 

General code for all other errors during initialization. 
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TPUSMESSAGE 


TPU$MESSAGE 



Writes error messages and strings using the built-in procedure 
MESSAGE. You can call this routine to have messages written and 
handled in a manner consistent with VAXTPU. This routine should 
only be used after TPU$EXECUTE_INIFILE. 

FORMAT 

TPUSMESSAGE string 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 


Note: The return status should be ignored because it is intended for use by the 



Put Message (SYS$PUTMSG) system service. 

ARGUMENT 

string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Message. The string argument is the address of a descriptor of a text to be 
written. It must be completely formatted. This routine does not append the 
message prefixes. However, the text is appended to the message buffer if 
one exists. In addition, if the buffer is mapped to a window, the window is 
updated. 
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TPUSPARSEINFO 


TPU$PARSEINFO 



Parses a command and builds the item list for TPU$INITIALIZE. This 
routine uses the Command Language Interpreter (CLI) routines to 
parse the current command. It makes queries about the command 
parameters and qualifiers that VAXTPU expects. The results of 
these queries are used to set up the proper information in an item 
list. The addresses of the user routines are used for those items in 
the list. The address of this list is the return value of the routine. It 
takes two parameters. 

FORMAT 

TPUSPARSEINFO fileio, calluser 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

fileio 

VMS Usage: vector_longword_unsigned 
type: bound procedure value 

access: read only 

mechanism: by descriptor 

File I/O routine. The fileio argument is the address of a descriptor of a file 
I/O routine 

calluser 

VMS Usage: vector_longword_unsigned 
type: bound procedure value 

access: read only 

mechanism: by descriptor 

Calluser routine. The calluser argument is the address of a descriptor of a 
calluser routine. 


TPU—43 






VAX Text Processing Utility (VAXTPU) Routines 
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TPU$TPU 

Invokes VAXTPU and is equivalent to the DCL EDIT/TPU command. 

FORMAT 

TPU$TPU command 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

command 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by descriptor 

Command string. The command argument is the address of a descriptor of a 
command line. Specify TPU as the command string. 

DESCRIPTION 

This routine takes the command string specified and passes it to the editor. 
VAXTPU uses the information from this command string for initialization 
purposes, just as though you had typed in the command at the DCL level. 

Using the simplified callable interface does not set TPU$CLOSE—SECTION. 
This feature allows you to make multiple calls to TPU$TPU without requiring 
you to open and close the section file on each call. 

CONDITION 

VALUES 

RETURNED 

Any condition value returned by TPU$INITIALIZE, TPU$EXECUTE —INFILE, 
TPU$CONTROL, and TPU$CLEANUP. 
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FILEIO 

The name of this routine can be either your own file I/O routine or 
the name of the VAXTPU file I/O routine (TPU$FILEIO). 

FORMAT 

FILEIO code, stream , data 

RETURNS 

VMS Usage: cond_value 
type: longword (usigned) 

access: write only 

mechanism: by reference 


Longword condition value. All utility routines return a condition in RO. 
Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 


ARGUMENTS code 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

an item code from VAXTPU that specifies what function to perform. 


stream 

VMS Usage: 
type: 
access: 
mechanism: 


unspecified 
longword (unsigned) 
modify 
by reference 


File description. The stream argument is the address of a data structure 
containing 4 longwords. This data structure is used to describe the file to be 
manipulated. 


data 

VMS Usage: 
type: 
access: 
mechanism: 


item _list _3 
longword (unsigned) 
modify 
by reference 


Stream data. The data argument is the address of an item list. 


Note: The data argument is the address of a descriptor depending on the item 
code you choose. 

The value of this parameter depends on which item code you specify. 
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FILEIO 


DESCRIPTION The bound procedure value of this routine is specified in the item list built by 

the callback routine. This routine is called to perform file operations. Instead 
of using your own file I/O routine, you can call TPU$FILEIO and pass it 
the parameters for any file operation that you do not want to handle. Note, 
however, that TPU$FILEIO must handle all I/O requests for any file it opens. 
Also, if it does not open the file, it cannot handle any I/O requests for the 
file. In other words, you cannot intermix the file operations between your 
own file I/O routine and the one supplied by VAXTPU. 
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HANDLER 



A user-written routine that performs condition handling. 

FORMAT 

HANDLER signal—vector, mechanism—vector 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return by value a condition 
value in RO. Condition values that can be returned by this routine are listed 
under "CONDITION VALUES RETURNED." 

ARGUMENTS 

signal—vector 

VMS Usage: arg_list 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

See the VAX/VMS System Services Reference Manual for information about the 
signal vector passed to a condition handler. 

mechanism—vector 

VMS Usage: arg_list 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

See the VAX/VMS System Services Reference Manual for information about the 
mechanism vector passed to a condition handler. 

DESCRIPTION 

If you need more information on writing condition handlers and the VAX 
Condition Handling Standard, refer to the Introduction to VAX/VMS System 
Routines. 

Instead of writing your own condition handler, you can use the default 
condition handler, TPU$HANDLER. If you want to write your own routine, 
you can refer to the routine description of TPU$HANDLER to see what 
VAXTPU's default condition handler does. 
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INITIALIZE 



Defaults all file specifications to a null string and all options to off 
(0). However, it does not have a default for the file I/O or calluser 
routine addresses. As a minimum requirement, the file I/O routine 
must be specified. Otherwise the routine TPU$INITIALIZE returns a 
failure status. 

FORMAT 

INITIALIZE callback 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENT 

callback 

VMS Usage: vector_longword_unsigned 
type: bound procedure value 

access: read only 

mechanism: by reference 

User-written callback initialization routine. The callback argument is the 
address of a routine that you must call to get initialization information (such 
as the address of a routine for handling file I/O). The DCL interface routine 
provided by VAXTPU (TPU$CLI_PARSE) can be used as the callback routine. 

A callback routine is a routine that you specify in a call to VAXTPU, which 
is in turn invoked by VAXTPU. The callback routine is passed to VAXTPU 
by specifying the address of the callback routine as a parameter to the 
TPU$INITIALIZE routine. The callback routine itself has no parameters. 
Rather, it returns the address of an item list that specifies initialization 
parameters. The following section describes the structure of the item list. 

Initialization parameters are listed by item code. This item list may be built at 
any time, but it must be available during the execution of TPU$INITIALIZE. 
The items for the list cannot be on the stack in the initial callback procedure. 
Therefore, they should not be stored in local variables in the language from 
which you are calling VAXTPU. 
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USER 

Allows your program to get control during a VAXTPU editing 
session (for example, to leave the editor temporarily and perform 
a calculation). 

This user-written routine is invoked by the VAXTPU built-in 

procedure CALI_USER. The built-in procedure CALI_USER passes 

two parameters to this routine. These parameters are then passed 
to the appropriate part of your application to be used as specified. 
(For example, they may be used as operands in a calculation within 
a FORTRAN program). Using the string routines provided by the 
VAX/VMS Run-Time Library, your application fills in the stringout 
parameter in the calluser routine, which returns the stringout value 
to the built-in procedure CALL_USER. 

FORMAT 

USER integer , stringin, stringout 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. All utility routines return a condition value in 

RO. Condition values that can be returned by this routine are listed under 
"CONDITION VALUES RETURNED." 

ARGUMENTS 

integer 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by descriptor 

The first parameter to the built-in procedure CALL—USER. This is an input- 
only parameter and must not be modified. 

stringin 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The second parameter to the built-in procedure CALL—USER. This is an 
input-only parameter and must not be modified. 
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USER 


stringout 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


This string is the return value for the built-in procedure CALL—USER. Your 
program should fill in this descriptor with a dynamic string allocated by the 
string routines provided by the VAX/VMS Run-Time Library. The VAXTPU 
editor frees this string when necessary. 


DESCRIPTION The description of the built-in procedure CALL—USER in the VAX Text 

Processing Utility Reference Manual has an example of a BASIC program that 
is a calluser routine. 


EXAMPLES 

Q INTEGER FUNCTION TPU$CALLUSER (x.y.z) 
IMPLICIT NONE 
INTEGER X 
CHARACTER*(*) Y 
STRUCTURE /dynamic/ Z 

INTEGER*2 length 
BYTE dtype 
BYTE class 
INTEGER ptr 
END STRUCTURE 
RECORD /dynamic/ Z 
CHARACTER*80 local.copy 
INTEGER rs,lclen 
INTEGER STR$COPY_DX 

local_copy * '<’ // y // ’>' 
lclen = LEN(Y) ♦ 2 

RS = STR$COPY_DX(Z,local_copy(1:lclen)) 

TPU$CALLUSER = RS 

END 


You can call the preceding FORTRAN program with a VAXTPU procedure. 
An example of such a procedure is as follows: 

0 PROCEDURE MY.CALL 
local status; 

status := CALL.USER (0,'ABCD'); 

MESSAGE('"' ♦ 

ENDPROCEDURE 
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Access Control List Editor routine 
See ACL Editor routine 
ACLEDIT$EDIT • ACL-3 
ACL Editor routine 
example* ACL-1 
introduction • ACL-1 


c 


CLI$DCL _PARSE • CLI-5 to CLI-7 
CLISDISPATCH • CLI-8 
CLI$GET_VALUE • CLI-9 
CLI$PRESENT • CLI-12 to CLI-14 
CLI routine 

example*CLI-1 to CLI-4 
introduction* CLI-1 
Command language routine 
See CLI routine 
CONVSCON VERT • CONV-8 
CON V$PASS_FILES • CONV-11 
CON V$PASS_OPTIONS • CONV-14 
CONVSRECLAIM • CONV-18 
Convert routine 
See CONV routine 
CONV routine 

examples*CONV-1 to CONV-7 
introduction • CONV-1 


DCX$MAKE_MAP • DCX-28 
DCX routine 

example • DCX-2 to DCX-1 1 
introduction • DCX-1 
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EDT$EDIT • EDT-3 
EDT routine 

examples *EDT-1 to EDT-2 
introduction • EDT-1 
user-written 

FILEIO • EDT-7 
WORKIO* EDT-11 
XLATE*EDT-13 
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FDL$CREATE • FDL-7 
FDL$GENER ATE • FDL-12 
FDL$PARSE • FDL-15 
FDL$RELE ASE • FDL-18 
FDL routine 

examples*FDL-1 to FDL-6 
introduction • FDL-1 
File Definition Language routine 
See FDL routine 
Full callable interface 
See VAXTPU routine 


D J 


Job controller 

request to symbiont • SMB-6 
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Data Compression/Expansion routine 
see DCX routine 

DCX$AN ALYZE_DAT A • DCX-12 
DCX$AN ALYZE_DONE•DCX-14 
DCX$ AN ALYZE_INIT • DCX-15 
DCX$COMPRESS_D AT A • DCX-18 
DCX$COMPRESS_DONE • DCX-20 
DCX$COMPRESS_INIT • DCX-21 
DCX$EXPAND_D AT A • DCX-23 
DCX$EXPAND_DONE • DCX-25 
DCX$EXPAND_INIT • DCX-26 


LBRSCLOSE•LBR-20 
LBR$DELETE_DATA • LBR-21 to LBR-22 
LBR$DELETE_KEY • LBR-23 to LBR-24 
LBRSFIND • LBR-25 to LBR-26 
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LBRSFLUSH • LBR-27 to LBR-28 
LBR$GET_HELP • LBR-31 to LBR-33 
LBR$GET_HISTORY • LBR-34 to LBR-35 
LBR$GET__INDEX • LBR-36 to LBR-37 
LBR$GET_RECORD • LBR-38 to LBR-39 

LBRSGET_HEADER »LBR-29 to LBR-30 

LBR$INI_CONTROL» LBR-40 to LBR-41 
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LBR$PUT_RECORD • LBR-58 to LBR-59 
LBR$REPLACE_KEY • LBR-60 to LBR-61 
LBR$RET_RMSSTV • LBR-62 
LBR$SEARCH • LBR-63 to LBR-64 
LBR$SET_INDEX • LBR-65 to LBR-66 
LBR$SET_LOCATE • LBR-67 
LBR$SET_MODULE • LBR-68 to LBR-69 
LBR$SET_MOVE • LBR-70 
LBR routine 

control index* LBR-7 
current index number 

setting • LBR-65 to LBR-66 
data record 

reading*LBR-38 to LBR-39 
writing • LBR-58 to LBR-59 
end-of-module record 
writing • LBR-55 
examples*LBR-7 to LBR-19 

creating a new library • LBR-7 to LBR-10 
deleting a module from a library • LBR-16 to 
LBR-19 

extracting a module from a library • LBR-13 
to LBR-16 

inserting a module into a library • LBR-10 to 
LBR-13 
header* LBR-2 
help text 

outputting • LBR-50 to LBR-54 
retrieving • LBR-31 to LBR-33 
index* LBR-2 

searching • LBR-63 to LBR-64 
introduction • LBR-1 to LBR-19 
library 

closing • LBR-20 

creating • LBR-46 to LBR-49 

help* LBR-1 

macro* LBR-1 

object* LBR-1 

opening • LBR-46 to LBR-49 


LBR routine 

library (cont'd.) 

shareable image*LBR-1 
structure*LBR-2 to LBR-5 
text • LBR-1 

types*LBR-1 to LBR-2 
user-developed • LBR-1 
library file 

flushing*LBR-27 to LBR-28 
library header information 

reading*LBR-29 to LBR-30 
retrieving *LBR-29 to LBR-30 
library index 

getting contents • LBR-36 to LBR-37 
initializing • LBR-40 to LBR-41 
searching for key*LBR-36 to LBR-37 
library key • LBR-2 

creating ASCII or binary • LBR-47 
deleting *LBR-23 to LBR-24 
finding • LBR-25 to LBR-26 
inserting • LBR-42 to LBR-43 
looking up*LBR-44 to LBR-45 
replacing • LBR-60 to LBR-61 
library update history record 
retrieving • LBR-34 to LBR-35 
locate mode 

setting record access mode to*LBR-67 
module* LBR-2 

accessing with RFA* LBR-25 to LBR-26 
deleting data records • LBR-21 to LBR-22 
deleting header*LBR-21 to LBR-22 
module header 

reading*LBR-68 to LBR-69 
setting*LBR-68 to LBR-69 
updating • LBR-68 to LBR-69 
move mode 

setting record access to*LBR-70 
summary *LBR-6 to LBR-7 
update history records 

writing • LBR-56 to LBR-57 
VAX RMS status value 
returning* LBR-62 
virtual memory 

recovering*LBR-27 to LBR-28 
Librarian routine 
See LBR routine 
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Print Symbiont Modification routine 
See PSM routine 
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PSM$_FUNNOTSUP • PSM-34 
PSM$PRINT »PSM-22 
PSM$READ_ITEM_DX • PSM-24 
PSM$REPLACE • PSM-26 
PSM$REPORT • PSM-31 
PSM routine* PSM-21 
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introduction • PSM-1 
user-written 
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USER-INPUT-ROUTINE • PSM-38 
USER-OUTPUT-ROUTINE • PSM-44 
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Queue 

execution • PSM-4 
generic* PSM-4 
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Simplified callable interface 
See VAXTPU routine 
SMB$CHECK_FOR_MESSAGE • SMB-16 
SMBSINITIALIZE • SMB-17 
SMBSRE AD_MESS AGE • SMB-19 
SMB$READ_MESSAGE_ITEM • SMB-22 
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See also Job Controller 
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introduction • SMB-1 
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SOR$END_SORT • SOR-33 
SOR$PASS_FILES • SOR-35 
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SOR$SORT_MERGE • SOR-44 
SOR$SPEC_FILE • SOR-47 
SOR routine *SOR-19 

examples *SOR-4 to SOR-19 
interface 

file* SOR-2 
record • SOR-2 
introduction • SOR-1 


SOR routine (cont'd.) 
reentrancy 

using context argument • SOR-3 
Sort/Merge routine 
See SOR routine 
Symbiont 

See also Queue 
allocating memory*SMB-4 
carriage control 

processing of*PSM-1 1 
connecting to a device*SMB-5 
device* PSM-2 
environments • SMB-5 
function • PSM-4, SMB-3 
input*PSM-2, SMB-1 

INPSMB.EXE file*SMB-1 
internal logic *PSM-5 

main format routine • PSM-13 
main input routine*PSM-10 
main output routine*PSM-14 
job controller 

communication with*SMB-1 
job controller request • SMB-6 
asynchronous • SMB-7 
processing • SMB-12 
reading* SMB-1 1 
responding • SMB-14 
synchronous • SMB-6 
modification • PSM-7 

format routine • PSM-12 
guidelines • PSM-8 
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input routine*PSM-9 
integration of routines • PSM-16 
output routine*PSM-13 
restrictions • PSM-8 
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multithreaded • PSM-3 
output • PSM-2, SMB-1 
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single stream • PSM-3, SMB-1 1 
SYSGEN MAXBUF parameter • PSM-7 
type* SMB-1 

user-written • SMB-1, SMB-4 
guidelines • SMB-4 
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Symbiont/Job Controller Interface routine 
See SMB routine 
Symbiont thread • PSM-3 
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See Symbiont 



User-written VAXTPU routine 
See VAXTPU routine 
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default* TPU-4 
return values*TPU-4 
universal symbols • TPU-4 
example*TPU-5, TPU-7 to TPU-22 
introduction • TPU-1 
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